# APIs for Volume Pricing

This document explains how to retrieve a list of Volume Pricing records using the Public API.

***

### 1. Endpoint

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

This endpoint allows you to retrieve a list of Volume Pricing records based on filtering and sorting parameters.

***

### 2. Request Headers

All 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 required header is missing or invalid, the request will be rejected.

***

### 3. Request Parameters

The GET request supports the following optional query parameters:

***

#### a. `limit`

Defines the maximum number of records returned.

* Must be a number
* Minimum value: **1**
* Maximum value: **20**
* If left empty, the default value is **20**

Example:

```
?limit=10
```

***

#### b. `query`

Search string used to filter records by **title** or **ID**.

* Must be a string
* Maximum length: **255 characters**

Example:

```
?query=pricing rule
```

***

#### c. `status`

Filter records by status.

* Can be left empty to retrieve all records
* If provided, only the following values are accepted:

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

Example:

```
?status=active
```

***

#### d. `sort`

Sort records by creation time.

* Can be left empty (default: newest records first)
* If provided, only accepts one of the following values:
  * `descrease`
  * `ascrease`

Example:

```
?sort=descrease
```

***

#### Example Full Request

```
GET https://wholesale.samita.io/api/v1/volume-pricings?limit=10&status=active&sort=descrease
```

***

### 4. API Response

***

#### 4.1 Error Responses

**401 – Unauthorized**

Returned when authentication fails.

Possible reasons:

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

***

**403 – This action is unauthorized**

Returned when the API key does not have sufficient permissions.

Each API key can be assigned the following permissions:

* View
* Create
* Update
* Delete

The **List Volume Pricing API** requires **View** permission.

***

**429 – Too Many Requests**

Returned when the rate limit is exceeded.

Current limits:

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

***

#### 4.2 Success Response

**200 – API Success**

Returned when the request is valid and successfully processed.

The response will return a list of Volume Pricing records in JSON format.

***

Example API success: 

```json
[
  {
    "id": 1,
    "title": "New Volume Pricing",
    "status": true,
    "type": "quantity",
    "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,
        "duplicated": false,
        "variant_pricing": true,
        "from_qty": "0",
        "from_amount": "0",
        "to_qty": "10",
        "to_amount": "0",
        "discount_groups": [
          {
            "name": "all",
            "type": "percent",
            "value": "10"
          }
        ],
        "variants": [
          {
            "id": 46747346763943,
            "duplicated": false,
            "from_qty": "0",
            "from_amount": "0",
            "to_qty": "10",
            "to_amount": "0",
            "discount_groups": [
              {
                "name": "all",
                "type": "percent",
                "value": "10"
              }
            ]
          }
        ]
      }
    ],
    "apply_market": {
      "type": "all",
      "handle": []
    },
    "discount_method": "variant",
    "discount_groups": [
      {
        "from_qty": "0",
        "from_amount": "0",
        "to_qty": "10",
        "to_amount": "0",
        "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"
  }
]
```