Discounts

Market id.

Bearer Store API token.

Market id.

The page to return, starting at 1.

The number of discounts to return on each page.

Return only active, scheduled, expired, or disabled discounts. Scheduled and expired values are derived from the current time.

Filter by type: percentage, fixed_amount, buy_x_get_y, bundle, free_gift, or tiered.

Return coupon discounts or automatic discounts.

Search by discount name or coupon code.

Sort by priority, name, type, activation, usage_count, ends_at, created_at, or updated_at. Defaults to priority. With ends_at, discounts without an end date sort last in either direction.

Sort in ascending (asc) or descending (desc) order.

Bearer Store API token.

Market id.

Bearer Store API token.

A name merchants can recognize when managing the discount.

Choose percentage, fixed_amount, buy_x_get_y, bundle, free_gift, or tiered.

For free_gift: offer or auto_add. On create, omitted or null means offer; on update, omitted or null keeps the current mode. With best_for_customer ranking a gift ranks at its full value (each gift's quantity-specific unit price times its granted quantity) whether or not it is in the cart yet, including advertised coupons before entry. Gift-only units never qualify for other discounts or inflate their ranking. A gift grant is eligible only when its complete set is channel-available, priced, within quantity limits and in stock alongside all physical merchandise, including quantity-priced items excluded from discounts. Stacked gift sets share stock in ranking order; a set is granted only if its complete demand fits after higher-ranked gifts. When automatic discounts and codes don't combine, an offer the shopper hasn't claimed doesn't keep codes out; a code that applies withdraws the offer.

For free_gift: a gift-only product_id, positive quantity per cart, and optional variant_id. Omit variant_id for a simple product; a variable product requires the exact variant_id that belongs to it.

For tiered: percentage or fixed_amount.

For tiered: 1–10 tiers with strictly ascending min_subtotal thresholds from 0 to money_amount_max, and positive values, in the base currency and its precision. Only the highest reached tier applies, chosen from the merchandise subtotal before any discount. Percentage values cannot exceed 100. Fixed savings can exceed the threshold but are capped at remaining eligible merchandise at checkout; merchandise never becomes negative. Other markets use the base amounts converted at the market's rate.

Use coupon when a shopper enters a code, or automatic when qualifying orders should receive the discount automatically.

Required for coupon activation. Use letters A–Z, digits, hyphens and underscores, up to code_max_length characters; the code is stored in upper case. Codes are unique within the market and matched without regard to case.

The discount's position when manual priority decides between competing offers. Omission uses 0 on both create and full replacement, which can conflict with another discount at that priority. Send an explicit unique whole number from priority_min through max_priority in the limits response.

The percentage reduction for a percentage discount. It must be greater than percentage_min_exclusive, no more than percentage_max, and use no more than percentage_decimal_places from the limits response.

Fixed discount amounts keyed by currency code. Include the store's base currency; additional entries must be currencies enabled for the market. Each amount must be greater than 0, at most money_amount_max, and fit that currency's minor-unit precision. A market currency without its own amount uses the base amount converted at the market's rate.

Apply the discount to the whole order or to selected products or variants, collections, or categories. Buy X Get Y and bundle offers define their items separately and use entire_order here.

Products to discount when applies_to is specific_products. A variable product target includes all of its current and future variants.

Exact variants to discount when applies_to is specific_products. You may combine these with simple or whole-variable product targets, up to max_products_per_discount targets in total.

The collections to discount when applies_to is specific_collections.

The categories to discount when applies_to is specific_categories.

Make the discount available to everyone, selected customers, or selected customer groups.

The customers who qualify when eligibility is specific_customers.

The customer groups that qualify when eligibility is specific_segments.

Skip items already on sale. Only percentage and fixed-amount discounts accept true; other types reject it with DISCOUNT_TARGETS_FORBIDDEN.

Require a minimum merchandise subtotal, keyed by currency code. Include the base currency when you set this condition; other market currencies without an entry use the converted base amount. It is checked before any discount. For percentage, fixed-amount and free gift discounts it counts only the items matched by applies_to, leaving out items excluded by exclude_sale_items and a free gift's own gift items. Buy X Get Y, bundle and tiered discounts use entire_order, so it counts every item in the cart, not only the Buy X, Get Y or bundle items. Gift-only items and items left out by the market's quantity-pricing setting never count. Every type accepts it.

Require between quantity_min and min_quantity_max eligible items from the limits response. Percentage, fixed-amount and free gift discounts accept this condition; Buy X Get Y, bundle and tiered discounts reject it with DISCOUNT_MIN_QUANTITY_FORBIDDEN.

Cap the amount saved, keyed by currency code. Percentage, bundle and tiered discounts accept it; fixed-amount, Buy X Get Y and free gift discounts reject it with DISCOUNT_MAX_DISCOUNT_FORBIDDEN.

Start the discount at this local store time, formatted as YYYY-MM-DDTHH:mm:ss.

Stop the discount at this local store time. It must be later than starts_at.

The total number of uses allowed. Send unlimited_sentinel (-1) or null for no limit, or a whole number from quantity_min through max_usage_limit in the limits response; an unlimited discount is returned as null. A use is held when an order is placed and counts toward the limit while the checkout is unpaid, so new orders are refused with DISCOUNT_USAGE_EXHAUSTED once the limit is reached. The use is given back if the checkout expires unpaid or the order is cancelled. A payment that arrives after its checkout expired still keeps its use, which can take the count past the limit. A discount with no usage_limit and no per_customer_limit counts no uses.

The number of uses allowed for each customer. Send unlimited_sentinel (-1) or null for no limit, or a whole number from quantity_min through max_per_customer_limit in the limits response; an unlimited discount is returned as null. A customer is recognised by account or by email address, ignoring case, so guest orders count toward that email's limit; an order with neither is not checked. Orders over the limit are refused with DISCOUNT_CUSTOMER_LIMIT_REACHED.

Give a use back to usage_limit and per_customer_limit when every item this discount reduced on an order is refunded, or the whole order is refunded. The use is returned shortly after the refund, following the setting the discount has at that moment. The release is final for that order and discount: payment capture or retry cannot reclaim it.

Restrict to a customer's first order. Earlier paid, cash-on-delivery or refunded orders under the same account or the same email address (ignoring case) disqualify; test and cancelled orders do not. Guests are recognised by email. An order with neither an account nor an email does not qualify.

Allow the storefront to show this coupon before checkout. Coupon discounts only; sending true for an automatic discount returns DISCOUNT_TARGETS_FORBIDDEN.

The quantity a shopper must add from the Buy X set.

The quantity rewarded from the Get Y set.

Make reward items free, reduce their remaining value by a percentage, or deduct a fixed amount from each reward item. The cheapest qualifying items are the rewards, whatever their order in the cart.

The percentage off each reward item, or the fixed amount deducted from each reward item in the store base currency, converted to the order currency at the market's exchange rate. Fixed means an amount off, not a final selling price. The deduction is capped at the remaining reward-item value. Omit this field when rewards are free. Fixed amounts use the base currency precision and the live money_amount_max.

The maximum number of complete Buy X Get Y sets that may apply to one order: a whole number from bxgy_max_uses_min through bxgy_max_uses_max in the limits response. Omit it or send null for no per-order cap; unlimited_sentinel (-1) is not accepted here.

Simple products, exact variants, collections, or categories that can satisfy Buy X. Each item contains item_type (product, variant, collection, category) and string item_id. An item qualifies when it matches any target in the list. Bought and reward items are always different units, even when the two lists overlap.

Simple products, exact variants, collections, or categories that can be rewarded as Get Y, independently of Buy X targets. The shopper adds reward items to the cart; the discount never adds them. Whole variable products cannot be saved as product targets; select their exact variants.

Use fixed_price for a set price or percentage for a percentage reduction on each complete bundle.

The price of one complete bundle, keyed by currency code. Include the base currency for fixed-price bundles; other market currencies without an entry use the converted base price.

The percentage reduction for each complete bundle when the value mode is percentage.

The maximum number of complete bundle sets discounted on one order. Send -1 or null for no limit; an unlimited bundle is returned as null.

The products or variants and quantities required for one complete bundle. Provide between bundle_components_min and bundle_components_max different components. A product component matches any variant of that product; a variant component matches only that variant.

Market id.

Discount id.

Bearer Store API token.

Market id.

Discount id.

Bearer Store API token.

A name merchants can recognize when managing the discount.

Choose percentage, fixed_amount, buy_x_get_y, bundle, free_gift, or tiered.

For free_gift: offer or auto_add. On create, omitted or null means offer; on update, omitted or null keeps the current mode. With best_for_customer ranking a gift ranks at its full value (each gift's quantity-specific unit price times its granted quantity) whether or not it is in the cart yet, including advertised coupons before entry. Gift-only units never qualify for other discounts or inflate their ranking. A gift grant is eligible only when its complete set is channel-available, priced, within quantity limits and in stock alongside all physical merchandise, including quantity-priced items excluded from discounts. Stacked gift sets share stock in ranking order; a set is granted only if its complete demand fits after higher-ranked gifts. When automatic discounts and codes don't combine, an offer the shopper hasn't claimed doesn't keep codes out; a code that applies withdraws the offer.

For free_gift: a gift-only product_id, positive quantity per cart, and optional variant_id. Omit variant_id for a simple product; a variable product requires the exact variant_id that belongs to it.

For tiered: percentage or fixed_amount.

For tiered: 1–10 tiers with strictly ascending min_subtotal thresholds from 0 to money_amount_max, and positive values, in the base currency and its precision. Only the highest reached tier applies, chosen from the merchandise subtotal before any discount. Percentage values cannot exceed 100. Fixed savings can exceed the threshold but are capped at remaining eligible merchandise at checkout; merchandise never becomes negative. Other markets use the base amounts converted at the market's rate.

Use coupon when a shopper enters a code, or automatic when qualifying orders should receive the discount automatically.

Required for coupon activation. Use letters A–Z, digits, hyphens and underscores, up to code_max_length characters; the code is stored in upper case. Codes are unique within the market and matched without regard to case.

The discount's position when manual priority decides between competing offers. Omission uses 0 on both create and full replacement, which can conflict with another discount at that priority. Send an explicit unique whole number from priority_min through max_priority in the limits response.

The percentage reduction for a percentage discount. It must be greater than percentage_min_exclusive, no more than percentage_max, and use no more than percentage_decimal_places from the limits response.

Fixed discount amounts keyed by currency code. Include the store's base currency; additional entries must be currencies enabled for the market. Each amount must be greater than 0, at most money_amount_max, and fit that currency's minor-unit precision. A market currency without its own amount uses the base amount converted at the market's rate.

Apply the discount to the whole order or to selected products or variants, collections, or categories. Buy X Get Y and bundle offers define their items separately and use entire_order here.

Products to discount when applies_to is specific_products. A variable product target includes all of its current and future variants.

Exact variants to discount when applies_to is specific_products. You may combine these with simple or whole-variable product targets, up to max_products_per_discount targets in total.

The collections to discount when applies_to is specific_collections.

The categories to discount when applies_to is specific_categories.

Make the discount available to everyone, selected customers, or selected customer groups.

The customers who qualify when eligibility is specific_customers.

The customer groups that qualify when eligibility is specific_segments.

Skip items already on sale. Only percentage and fixed-amount discounts accept true; other types reject it with DISCOUNT_TARGETS_FORBIDDEN.

Require a minimum merchandise subtotal, keyed by currency code. Include the base currency when you set this condition; other market currencies without an entry use the converted base amount. It is checked before any discount. For percentage, fixed-amount and free gift discounts it counts only the items matched by applies_to, leaving out items excluded by exclude_sale_items and a free gift's own gift items. Buy X Get Y, bundle and tiered discounts use entire_order, so it counts every item in the cart, not only the Buy X, Get Y or bundle items. Gift-only items and items left out by the market's quantity-pricing setting never count. Every type accepts it.

Require between quantity_min and min_quantity_max eligible items from the limits response. Percentage, fixed-amount and free gift discounts accept this condition; Buy X Get Y, bundle and tiered discounts reject it with DISCOUNT_MIN_QUANTITY_FORBIDDEN.

Cap the amount saved, keyed by currency code. Percentage, bundle and tiered discounts accept it; fixed-amount, Buy X Get Y and free gift discounts reject it with DISCOUNT_MAX_DISCOUNT_FORBIDDEN.

Start the discount at this local store time, formatted as YYYY-MM-DDTHH:mm:ss.

Stop the discount at this local store time. It must be later than starts_at.

The total number of uses allowed. Send unlimited_sentinel (-1) or null for no limit, or a whole number from quantity_min through max_usage_limit in the limits response; an unlimited discount is returned as null. A use is held when an order is placed and counts toward the limit while the checkout is unpaid, so new orders are refused with DISCOUNT_USAGE_EXHAUSTED once the limit is reached. The use is given back if the checkout expires unpaid or the order is cancelled. A payment that arrives after its checkout expired still keeps its use, which can take the count past the limit. A discount with no usage_limit and no per_customer_limit counts no uses.

The number of uses allowed for each customer. Send unlimited_sentinel (-1) or null for no limit, or a whole number from quantity_min through max_per_customer_limit in the limits response; an unlimited discount is returned as null. A customer is recognised by account or by email address, ignoring case, so guest orders count toward that email's limit; an order with neither is not checked. Orders over the limit are refused with DISCOUNT_CUSTOMER_LIMIT_REACHED.

Give a use back to usage_limit and per_customer_limit when every item this discount reduced on an order is refunded, or the whole order is refunded. The use is returned shortly after the refund, following the setting the discount has at that moment. The release is final for that order and discount: payment capture or retry cannot reclaim it.

Restrict to a customer's first order. Earlier paid, cash-on-delivery or refunded orders under the same account or the same email address (ignoring case) disqualify; test and cancelled orders do not. Guests are recognised by email. An order with neither an account nor an email does not qualify.

Allow the storefront to show this coupon before checkout. Coupon discounts only; sending true for an automatic discount returns DISCOUNT_TARGETS_FORBIDDEN.

The quantity a shopper must add from the Buy X set.

The quantity rewarded from the Get Y set.

Make reward items free, reduce their remaining value by a percentage, or deduct a fixed amount from each reward item. The cheapest qualifying items are the rewards, whatever their order in the cart.

The percentage off each reward item, or the fixed amount deducted from each reward item in the store base currency, converted to the order currency at the market's exchange rate. Fixed means an amount off, not a final selling price. The deduction is capped at the remaining reward-item value. Omit this field when rewards are free. Fixed amounts use the base currency precision and the live money_amount_max.

The maximum number of complete Buy X Get Y sets that may apply to one order: a whole number from bxgy_max_uses_min through bxgy_max_uses_max in the limits response. Omit it or send null for no per-order cap; unlimited_sentinel (-1) is not accepted here.

Simple products, exact variants, collections, or categories that can satisfy Buy X. Each item contains item_type (product, variant, collection, category) and string item_id. An item qualifies when it matches any target in the list. Bought and reward items are always different units, even when the two lists overlap.

Simple products, exact variants, collections, or categories that can be rewarded as Get Y, independently of Buy X targets. The shopper adds reward items to the cart; the discount never adds them. Whole variable products cannot be saved as product targets; select their exact variants.

Use fixed_price for a set price or percentage for a percentage reduction on each complete bundle.

The price of one complete bundle, keyed by currency code. Include the base currency for fixed-price bundles; other market currencies without an entry use the converted base price.

The percentage reduction for each complete bundle when the value mode is percentage.

The maximum number of complete bundle sets discounted on one order. Send -1 or null for no limit; an unlimited bundle is returned as null.

The products or variants and quantities required for one complete bundle. Provide between bundle_components_min and bundle_components_max different components. A product component matches any variant of that product; a variant component matches only that variant.

Market id.

Bearer Store API token.

Unique discount UUIDs, at most list_max_limit from the limits endpoint.

delete, enable or disable.

Market id.

Discount id.

Bearer Store API token.

Market id.

Discount id.

Bearer Store API token.

Market id.

Discount id.

Bearer Store API token.

Market id.

Bearer Store API token.

Market id.

Bearer Store API token.

Use single to apply one discount per order, chosen by priority_mode, or stack to let every eligible automatic discount and up to coupon_limit codes apply together.

How discounts are ranked: best_for_customer by each discount's own saving, manual by priority number, lowest first. The ranking picks the single discount, fills the coupon limit, and decides which offer keeps items two offers both need. It ranks discounts one by one rather than searching for the largest combined saving.

The maximum number of codes that may apply to one order in stack mode, from 1 to the platform maximum (currently 5). Automatic discounts do not count.

In stack mode, true lets codes apply alongside automatic discounts; false lets codes apply only when no automatic discount applies. No effect in single mode.

When false, items with quantity pricing get no discount and do not count toward minimum spend, minimum quantity or tiers. When true, they are discounted like any other item, on top of their quantity price.