# APIs for Wholesale Pricing

This document describes how to use the Public API to retrieve the list of Wholesale Pricing records from the Samita Wholesale application.

***

### 1. Endpoint

To retrieve the Wholesale Pricing list, use the following API endpoint:

```
GET - https://wholesale.samita.io/api/v1/wholesale-pricings
```

***

### 2. Request Headers

All API requests must include the following required headers:

| Header                  | Description                                     | Required |
| ----------------------- | ----------------------------------------------- | -------- |
| **`X-SAMITA-API-KEY`**  | API key provided in the Wholesale app           | Yes      |
| **`X-SAMITA-SHOP-URL`** | Shopify shop domain in format xxx.myshopify.com | Yes      |
| **`CONTENT-TYPE`**      | Must be `application/json`                      | Yes      |

If any of these headers are missing, the request will be rejected.

***

### 3. Request Parameters (Query / Body)

The following parameters can be included to customize the API request:

| Parameter | Description                                                   | Required |
| --------- | ------------------------------------------------------------- | -------- |
| `limit`   | Defines the maximum number of records returned in one request | No       |
| `query`   | Used to search records by title or ID                         | No       |
| `status`  | Used to filter records by their status                        | No       |
| `sort`    | Used to sort records by creation time                         | No       |

#### a. limit

* Defines the maximum number of records returned in one request
* Must be a numeric value
* Minimum value: **1**
* Maximum value: **20**
* Optional parameter
* If left empty, the default value will be **20**

Example:

```
limit=10
```

***

#### b. query

* Used to search records by title or ID
* Must be a string value
* Maximum length: **255 characters**
* Optional parameter

Example:

```
query=pricing rule
```

***

#### c. status

* Used to filter records by their status
* Optional parameter
* If left empty, the API will return all records
* If provided, only the following values are accepted:

| Value    | Description         |
| -------- | ------------------- |
| `active` | Only active records |
| `draft`  | Only draft records  |

Any other value will be rejected.

Example:

```
status=active
```

***

#### d. sort

* Used to sort records by creation time
* Optional parameter
* If left empty, records will be sorted by newest created first
* Only two values are accepted:

| Value       | Description                |
| ----------- | -------------------------- |
| `descrease` | Sort from newest to oldest |
| `ascrease`  | Sort from oldest to newest |

Example:

```
sort=descrease
```

***

**Example request:**

```
GET /wholesale-pricing?page=1&limit=20&status=active&sort=descrease
```

### 4. API Response

The API will return one of the following HTTP status codes:

#### a. Error Responses

**401 – Unauthorized**

This error occurs when the request is not properly authenticated.

Possible reasons:

* Missing shop URL
* Missing API key
* Incorrect shop URL
* Incorrect API key
* API key does not match the provided shop

***

**403 – This action is unauthorized**

This error occurs when the API key does not have sufficient permissions.

Each API key can be assigned the following permissions:

* View
* Create
* Update
* Delete

The Wholesale Pricing List API requires the **View** permission.\
If the API key does not have View permission, this error will be returned.

***

**429 – Too Many Requests**

This error occurs when the request exceeds the allowed rate limit.

Current rate limits:

* Maximum **1 request per 5 minutes**
* Maximum **50 requests per day**

If these limits are exceeded, the system will return this error.

***

#### b. Success Response

**200 – API Success**

* The request is valid
* Authentication is successful
* Data is returned correctly
* The Wholesale Pricing list is provided in JSON format

***

Example API success: 

```json
[
  {
    "id": 1,
    "title": "New Wholesale Pricing",
    "status": true,
    "apply_customer": {
      "type": "all",
      "tags": []
    },
    "exclude_customer": {
      "type": "none",
      "tags": []
    },
    "apply_product": {
      "type": "all",
      "product_ids": [],
      "product_tags": [],
      "collection_ids": [],
      "apply_for_variants": false
    },
    "exclude_product": {
      "type": "none",
      "product_ids": [],
      "collection_ids": []
    },
    "discount_for_variants": [
      {
        "id": 8516448190631,
        "variant_pricing": true,
        "variants": [
          {
            "id": 46747346763943,
            "discount_groups": [
              {
                "name": "all",
                "type": "percent",
                "value": "10"
              }
            ]
          }
        ]
      }
    ],
    "apply_market": {
      "type": "all",
      "handle": []
    },
    "discount_group": {
      "type": "percent",
      "value": "10"
    },
    "active_date": {
      "types": [],
      "start_at": "",
      "end_at": ""
    },
    "created_at": "2026-01-15T10:00:00",
    "updated_at": "2026-01-15T10:00:00"
  }
]
```