Ctrlk
Get SAMITA
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Create Volume Pricing using APIs

Create a new Volume Pricing rule via the Public API, including the full request body reference.

This document explains how to create a new Volume Pricing rule using the Public API.

1. Endpoint

To create a new Volume 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:

b. title (Required)

  • The name used to identify the Volume 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:

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:

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:

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:

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

Note:

from/to_qty is used when "type(d)=quantity"

from/to_amount is used when "type(d)=amount"

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

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 (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:

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:

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:

Rules are the same as described above for discount types and values.

m. active_date

Used to configure start and end time for the pricing rule.

Structure:

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

  • Volume Pricing record created successfully

  • Response returned in JSON format

PreviousAPIs for Volume PricingNextUpdate/Edit Volume Pricing using APIs

Last updated

Was this helpful?