# Create Volume Pricing using APIs
This document explains how to create a new Volume Pricing rule using the Public API.
***
### 1. Endpoint
To create a new Wholesale Pricing record, use the following endpoint:
```
POST - https://wholesale.samita.io/api/v1/volume-pricings
```
This endpoint allows you to create a new Volume Pricing configuration.
***
### 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 required header is missing, the request will be rejected.
***
### 3. Request Body
#### a. General Format
The data used to create Volume Pricing must be sent in **JSON format**.\
A sample JSON structure is provided at the end of this document.
**Sample Request JSON:**
```json
{
"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 date", "end date"],
"start_at": "2026-01-15T10:00:00",
"end_at": "2026-01-15T10:00:00"
}
}
```
***
#### b. title (Required)
* The name used to identify the Wholesale Pricing record
* Must be a string
* Maximum length: **255 characters**
***
#### c. status (Required)
* Defines whether the record is active or not
* Accepts only the following values:
| Value | Description |
| ------- | ------------------------ |
| `true` | Pricing rule is active |
| `false` | Pricing rule is inactive |
***
#### d. type (Required)
Defines whether volume pricing is calculated by quantity or amount.
Accepted values:
* `quantity`
* `amount`
#### e. apply\_customer (Required)
Defines which customers are eligible for this pricing rule.
**Structure:**
```
"apply_customer": {
"type": "all",
"tags": []
}
```
**type**
Accepted values (only one of the following):
* `all` – Apply to all customers
* `logged` – Apply only to logged-in customers
* `non-logged` – Apply only to guest customers
* `customer-tags` – Apply only to customers with specific tags
**tags**
* Required only when `type == customer-tags`
* Must be a comma-separated array
* Example: `["wholesale","b2b"]`
If type is not `customer-tags`, this field can be ignored.
***
#### f. exclude\_customer
Used to exclude specific customers from the pricing rule.
**Structure:**
```
"exclude_customer": {
"type": "none",
"tags": []
}
```
**type**
* Default value: `none`
* Accepted values:
| Value | Description |
| --------------- | --------------------------- |
| `none` | Do not exclude any customer |
| `customer-tags` | Exclude customers by tags |
**tags**
* Required only when `type == customer-tags`
* Comma-separated array
* Example: `["vip","internal"]`
***
#### g. apply\_product (Required)
Defines which products the pricing rule will be applied to.
**Structure:**
```
"apply_product": {
"type": "all",
"product_ids": [],
"product_tags": [],
"collection_ids": [],
"apply_for_variants": false
}
```
**type**
Accepted values:
* `all`
* `products`
* `collections`
* `product-tags`
**product\_ids**
* Required only when `type == products`
* Comma-separated list of product IDs
* Example: `[1,2,3]`
**product\_tags**
* Required only when `type == product-tags`
* Example: `["tag1","tag2"]`
**collection\_ids**
* Required only when `type == collections`
* Example: `[1,2,3]`
**apply\_for\_variants**
* Determines whether discounts can be configured per variant
* Accepted values: `true` or `false`
* Default value: `false`
***
#### h. exclude\_product
Defines products to be excluded from the rule.
**Structure:**
```
"exclude_product": {
"type": "none",
"product_ids": [],
"collection_ids": []
}
```
**type**
* Default: `none`
* Accepted values:
| Value | Description |
| ------------- | ---------------------------- |
| `none` | Do not exclude any product |
| `products` | Exclude specific products |
| `collections` | Exclude specific collections |
Other fields are required only depending on the selected type.
***
#### i. discount\_for\_variants
Defines discount configuration at the **product and/or variant level**.
* Leave this field empty if `apply_product.apply_for_variants == false`.
* If `apply_product.apply_for_variants == true`, this field is required.
* The structure must be an **array of product configurations**.
**Structure:**
**i.1. id (required)**
* Product ID.
* Must match an existing product.
**i.2. duplicated**
Indicates whether the product has multiple quantity/amount ranges.
Accepted values:
* `true`
* `false`
Rules:
* If `true`: the product contains multiple quantity/amount ranges.
* If `false`: the product has only one quantity/amount range.
**i.3. from\_qty / from\_amount**
Starting quantity or amount of the range.
Rules:
* The first item may be empty (defaults to 1).
* All subsequent items are required.
**i.4. to\_qty / to\_amount**
Ending quantity or amount of the range.
Rules:
* Can be empty (will automatically be calculated as the next item's `from` value minus 1).
* If provided, it must be less than the next item's `from` value.
Examples:
* Item 1: from:0 – to:10 → Item 2: from:11 – to:20
* Item 1: from:0 – to:blank → Item 2: from:10 – to:blank
* Item 1: from:blank – to:10 → Item 2: from:11 – to:blank
{% hint style="info" %}
**Note:**
**from/to\_qty is used when "type(d)=quantity"**
**from/to\_amount is used when "type(d)=amount"**
{% endhint %}
**i.5. discount\_groups (Product Level)**
Defines discount configuration for each quantity/amount range at the **product level**.
* Required if `variant_pricing == false`.
* Leave empty if `variant_pricing == true`.
* Must be an array of discount objects corresponding to the configured `apply_customer.type`.
**Structure:**
```
{
"name": "all",
"type": "percent",
"value": "10"
}
```
**+ name**
Accepted values:
* `all` (if `apply_customer.type == all`)
* `logged` (if `apply_customer.type == logged`)
* `non-logged` (if `apply_customer.type == non-logged`)
If another value is provided, it will be treated as a **customer tag**, and it must match one of the tags defined in `apply_customer.tags`.
**+ type**
Defines the discount type.
Accepted values:
* `percent` – Percentage discount
* `amount` – Fixed amount deducted from the price
* `fixed-amount` – Final fixed price
**+ value**
* Must be a number
* Must be greater than 0
* If `type == percent`, value must be less than 100
**i.6. variant\_pricing**
Indicates whether discount is applied at the variant level.
Accepted values:
* `true`
* `false`
**i.7. variants**
Defines variant-level discount configuration.
* Required if `variant_pricing == true`
* Leave empty if `variant_pricing == false`
* Must be an array of variant configurations
**Structure:**
```
{
"id": 46747346763943,
"duplicated": false,
"from_qty": "0",
"from_amount": "0",
"to_qty": "10",
"to_amount": "0",
"discount_groups": [
{
"name": "all",
"type": "percent",
"value": "10"
}
]
}
```
**+ id (required)**
* Variant ID.
**+ duplicate**
Indicates whether the variant has multiple quantity/amount ranges.
Accepted values:
* `true`
* `false`
Rules:
* If `true`: the variant contains multiple ranges.
* If `false`: the variant has only one range.
**+ from\_qty / from\_amount**
Starting quantity or amount.
Rules:
* First item may be empty (defaults to 1).
* All subsequent items are required.
**+ to\_qty / to\_amount**
Ending quantity or amount.
Rules:
* Can be empty (auto-calculated as next item's `from` minus 1).
* If provided, must be less than the next item's `from` value.
Examples:
* Item 1: from:0 – to:10 → Item 2: from:11 – to:20
* Item 1: from:0 – to:blank → Item 2: from:10 – to:blank
* Item 1: from:blank – to:10 → Item 2: from:11 – to:blank
**+ discount\_groups (Variant Level)**
Defines discount configuration per quantity/amount range at the variant level.
Rules:
* If `apply_customer.type` is:
* `all`
* `logged`
* `non-logged`\
→ The array must contain only one item.
* If `apply_customer.type == customer-tags`\
→ The array must contain multiple items (one per customer tag).
*
**name**
Accepted values:
* `all`
* `logged`
* `non-logged`
If another value is provided, it will be treated as a customer tag and must match a tag defined in `apply_customer.tags`.
**type**
Accepted values:
* `percent`
* `amount`
* `fixed-amount`
**value**
* Must be a number
* Must be greater than 0
* If `type == percent`, value must be less than 100
***
#### j. apply\_market (Required)
Defines which Shopify markets the rule applies to.
**Structure:**
```
"apply_market": {
"type": "all",
"handle": []
}
```
**type**
Accepted values:
* `all`
* `specific-market`
**handle**
* Required only when `type == specific-market`
* Comma-separated list of market handles
* Example: `["japan","us"]`
***To get Market handle, kindly do as follow:***
* In Shopify Admin page, go to **Markets** section > Click on **More actions** > Choose **Edit Market** handles > Copy the handle showing there:
***
#### k. discount\_methods (Required)
Accepted values:
* `variant` → Same Variant
* `across_group` → Mix Variants
* `within_each_group` → Mix Products
These correspond to the options available in the app.
Example:
```
"discount_method": "variant",
```
#### l. discount\_group (Required)
Defines quantity/amount ranges and discount values.
**from\_qty / from\_amount**
**to\_qty / to\_amount**
Same validation rules as described above.
Accepted "type" values:
* `percent`
* `amount`
* `fixed-amount`
value:
* Must be > 0
* If percent → must be < 100
Structure:
```
"discount_groups": [
{
"from_qty": "0",
"from_amount": "0",
"to_qty": "10",
"to_amount": "0",
"type": "percent",
"value": "10"
}
],
```
Rules are the same as described above for discount types and values.
***
#### k. active\_date
Used to configure start and end time for the pricing rule.
Structure:
```
"active_date": {
"types": ["start_date", "end_date"],
"start_at": "2026-01-15 10:00:00",
"end_at": "2026-01-15 10:00:00"
}
```
**types**
* Optional
* Accepted values: `start_date`, `end_date`
* Can include one or both, separated by comma
* Example: `["start_date","end_date"]`
**start\_at**
* Required if `types` includes `start_date`
* Format: `YYYY-MM-DD HH:MM:SS`
**end\_at**
* Required if `types` includes `end_date`
* Format: `YYYY-MM-DD HH:MM:SS`
***
### 4. API Response
#### a. Error Responses
**401 – Unauthorized**
Possible reasons:
* Missing shop URL
* Missing API key
* Invalid shop URL
* Invalid API key
* API key does not match the shop
***
**403 – This action is unauthorized**
* API key does not have Create permission
* Each API key can have: View, Create, Update, Delete permissions
* This API requires **Create** permission
* Also returned when a provided ID does not exist
***
**429 – Too Many Requests**
* Rate limit exceeded
* Maximum allowed:
| Limit | Value |
| ----------------- | ----------------------- |
| Request frequency | 1 request per 5 minutes |
| Daily limit | 50 requests per day |
***
#### b. Success Response
**200 – API Success**
* Wholesale Pricing record created successfully
* Response returned in JSON format
```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"
}
```
