Discounts

Get discount limits

GET read_markets

Fetch discount validation limits and enum sets.

Returns everything needed to build a valid discount without hardcoding: the per-market cap, name/code lengths, the enum sets (types, activations, applies-to, customer eligibilities, BXGY get/item types, statuses), per-type capability flags, relation caps (max products/collections/categories/customers/groups per discount, max BXGY items), value ranges (percentage bounds, money maximums, quantity and priority ranges, usage-limit caps, the -1 unlimited sentinel), and the list/sort vocabulary.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

404 MARKET_NOT_FOUND
Market does not exist in this store.

Response

200

Sample response

{
  "success": true,
  "data": {
    "max_per_market": 10000,
    "name_max_length": 255,
    "code_max_length": 50,
	"types": ["percentage", "fixed_amount", "free_shipping", "buy_x_get_y", "bundle"],
    "activations": ["coupon", "automatic"],
    "applies_to": ["entire_order", "specific_products", "specific_collections", "specific_categories"],
    "customer_eligibilities": ["everyone", "specific_customers", "specific_segments"],
    "statuses": ["active", "scheduled", "expired", "disabled"],
    "bxgy_get_types": ["free", "percentage", "fixed"],
	"bxgy_item_types": ["product", "collection", "category"],
	"bundle_value_modes": ["fixed_price", "percentage"],
	"bundle_item_types": ["product", "variant"],
	"bundle_components_min": 2,
	"bundle_components_max": 20,
	"bundle_item_quantity_max": 100,
	"bundle_max_sets_min": 1,
	"bundle_max_sets_max": 1000000,
    "max_products_per_discount": 250,
    "max_customers_per_discount": 100,
    "max_usage_limit": 1000000,
    "percentage_max": 100,
    "unlimited_sentinel": -1,
    "sort_columns": ["priority", "name", "type", "activation", "usage_count", "created_at", "updated_at"],
    "sort_directions": ["asc", "desc"],
    "default_sort": "priority",
    "default_direction": "asc"
  }
}

List discounts

GET read_markets

List a market's discounts.

Returns paginated discounts with their definitions; relation ids are returned by the detail endpoint, not the list. Filters: status (active/scheduled/expired/disabled — status always reflects the current schedule, so filtering by expired finds every discount whose end date has passed), type, activation, and search by name or coupon code. Pagination and sorting bounds come from the discount limits.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`

Query parameters

Name	Type	Description
`page`	`integer`	Page number. Example: `1`
`per_page`	`integer`	Page size (service-capped). Example: `20`
`status`	`string`	Filter by status: `active`, `scheduled`, `expired`, or `disabled`. Status reflects the schedule, so `expired` matches discounts whose end date has passed. Example: `active`
`type`	`string`	Filter by type: `percentage`, `fixed_amount`, `free_shipping`, `buy_x_get_y`, or `bundle`. Example: `percentage`
`activation`	`string`	Filter by activation: `coupon` or `automatic`. Example: `coupon`
`search`	`string`	Search by discount name or coupon code. Example: `summer`
`sort_by`	`string`	Sort column from the discount limits (priority, name, type, activation, usage_count, created_at, updated_at). Example: `priority`
`sort_direction`	`string`	Sort direction. Example: `asc`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 MARKET_DISCOUNT_FILTER_INVALID
status/type/activation filter is not a supported value.
400 MARKET_DISCOUNT_SEARCH_TOO_LONG
Search query exceeds the discount limits max length.
400 MARKET_DISCOUNT_LIST_INVALID_SORT_BY
sort_by is not a discount sort column.
400 MARKET_DISCOUNT_LIST_INVALID_SORT_DIRECTION
sort_direction is not asc or desc.
404 MARKET_NOT_FOUND
Market does not exist in this store.

Response

200

Sample response

{
  "success": true,
  "data": {
    "discounts": [{
    "id": "7c4b1e2f-9a8d-4c3b-b2a1-0f9e8d7c6b5a",
    "store_id": "9a1f2c3d-4e5f-6789-abcd-ef0123456789",
    "market_id": "1c807b16-8a93-4f13-b998-1226c87d57ac",
    "name": "Summer sale",
    "type": "percentage",
    "activation": "coupon",
    "code": "SUMMER20",
    "status": "active",
    "priority": 10,
    "value": 20,
    "amounts": null,
    "applies_to": "entire_order",
    "exclude_sale_items": false,
    "min_subtotal": {"USD": "50.00"},
    "min_quantity": null,
    "max_discount": {"USD": "100.00"},
    "usage_limit": -1,
    "usage_count": 42,
    "per_customer_limit": 1,
    "customer_eligibility": "everyone",
    "first_order_only": false,
    "show_in_cart": true,
    "product_ids": [],
    "collection_ids": [],
    "category_ids": [],
    "customer_ids": [],
    "group_ids": [],
    "products": [],
    "collections": [],
    "categories": [],
    "customers": [],
    "groups": [],
    "bxgy_buy_items": [],
    "bxgy_get_items": [],
    "bundle_value_mode": null,
    "bundle_percentage": null,
    "bundle_prices": null,
    "bundle_max_sets": null,
    "bundle_items": [],
    "can_view_products": true,
    "can_view_customers": false,
    "starts_at": "Aug 1, 2026, 12:00 AM",
    "starts_at_iso": "2026-08-01T00:00:00",
    "ends_at": "Aug 31, 2026, 11:59 PM",
    "ends_at_iso": "2026-08-31T23:59:59",
    "created_at": "Jul 1, 2026, 10:15 AM",
    "updated_at": "Jul 9, 2026, 6:40 PM"
  }],
    "total": 1,
    "market_total": 14,
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  }
}

Create a discount

POST write_markets

Create a discount in a market.

Creates a discount. The validation matrix is strict per type: percentage requires value; fixed_amount requires a base-currency amounts entry; free_shipping has no value; buy_x_get_y requires quantities, get mode, and non-empty buy/get target sets; bundle requires 2–20 unique product/variant components plus either fixed set prices or a percentage off. Bundle and BXGY component IDs must resolve inside the token's store. coupon requires a case-insensitively unique code while automatic rejects the code field. Priority is unique per market. Generic targeting and eligibility lists are accepted only when selected by their matching mode. Fires discounts/create.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`name` required	`string`	Discount name. Example: `Summer sale`
`type` required	`string`	`percentage`, `fixed_amount`, `free_shipping`, `buy_x_get_y`, or `bundle`. Each type requires exactly its own value fields and rejects the others'. Example: `percentage`
`activation` required	`string`	`coupon` (requires `code`) or `automatic` (rejects `code`). Example: `coupon`
`code`	`string`	Coupon code — required for `coupon` activation, unique per market case-insensitively, stored uppercased. Example: `SUMMER20`
`priority` required	`integer`	Evaluation priority — unique per market. Example: `10`
`value`	`number`	Percentage value (0–100] — `percentage` type only. Example: `20`
`amounts`	`object`	Currency-code → amount map — `fixed_amount` type only. The store's base currency entry is required; other entries must be market currencies. Example: `{"USD": "10.00", "EUR": "8.50"}`
`applies_to` required	`string`	`entire_order`, `specific_products`, `specific_collections`, or `specific_categories`. Free shipping, BXGY, and bundle discounts must be `entire_order`. Example: `entire_order`
`product_ids`	`array<integer>`	Target product ids — required exactly when applies_to is `specific_products`. Example: `[12, 34]`
`collection_ids`	`array<string>`	Target collection ids — required exactly when applies_to is `specific_collections`. Example: `["9a1f..."]`
`category_ids`	`array<integer>`	Target category ids — required exactly when applies_to is `specific_categories`. Example: `[7]`
`customer_eligibility` required	`string`	`everyone`, `specific_customers`, or `specific_segments`. Example: `everyone`
`customer_ids`	`array<string>`	Eligible customer ids — required exactly for `specific_customers`. Example: `["5b2e..."]`
`group_ids`	`array<string>`	Eligible customer-group ids — required exactly for `specific_segments`. Example: `["6c3f..."]`
`exclude_sale_items`	`boolean`	Skip items already on sale. Example: `false`
`min_subtotal`	`object`	Minimum order subtotal per currency (base currency entry required when set). Example: `{"USD": "50.00"}`
`min_quantity`	`integer`	Minimum order item count. Accepted only by discount types whose limits capability declares support. Example: `2`
`max_discount`	`object`	Cap on the computed discount per currency. Percentage type only. Example: `{"USD": "100.00"}`
`starts_at`	`string`	Schedule start in the store timezone, formatted as YYYY-MM-DDTHH:mm:ss with no timezone suffix. Status derives from the window. Example: `2026-08-01T00:00:00`
`ends_at`	`string`	Schedule end in the same store-local format — must be after starts_at. Example: `2026-08-31T23:59:59`
`usage_limit`	`integer`	Total redemption cap; -1 = unlimited. Example: `-1`
`per_customer_limit`	`integer`	Per-customer redemption cap; -1 = unlimited. Example: `1`
`first_order_only`	`boolean`	Restrict to a customer's first order. Example: `false`
`show_in_cart`	`boolean`	Surface a coupon in the cart before checkout. Automatic discounts reject this field when true. Example: `false`
`bxgy_buy_quantity`	`integer`	BXGY: quantity the buyer must add from the buy set. Example: `2`
`bxgy_get_quantity`	`integer`	BXGY: quantity granted from the get set. Example: `1`
`bxgy_get_type`	`string`	BXGY: `free`, `percentage` (requires bxgy_get_value in (0–100]), or `fixed` (requires a positive bxgy_get_value). Example: `free`
`bxgy_get_value`	`number`	BXGY: get-side value for `percentage`/`fixed` get types; forbidden for `free`. Example: `50`
`bxgy_max_uses`	`integer`	BXGY: how many times the pattern may apply per order. Example: `1`
`bxgy_buy_items`	`array<object>`	BXGY buy set: {item_type: product\|collection\|category, item_id} — no duplicates. Example: `[{"item_type": "product", "item_id": "12"}]`
`bxgy_get_items`	`array<object>`	BXGY get set — same shape as the buy set. Example: `[{"item_type": "product", "item_id": "34"}]`
`bundle_value_mode`	`string`	Bundle pricing mode: `fixed_price` or `percentage`. Example: `fixed_price`
`bundle_prices`	`object`	Bundle fixed set price by currency. Required for fixed_price mode and must include the store base currency. Example: `{"USD": "75.00"}`
`bundle_percentage`	`number`	Percentage off each complete component set. Required for percentage mode. Example: `15`
`bundle_max_sets`	`integer`	Maximum complete sets discounted per order; omit or use -1 for unlimited. Example: `2`
`bundle_items`	`array<object>`	Bundle components: 2–20 unique `{item_type: product\|variant, item_id, quantity}` rows. Every target must belong to the store. Example: `[{"item_type": "product", "item_id": "12", "quantity": 1}, {"item_type": "variant", "item_id": "45", "quantity": 2}]`

Errors

400 DISCOUNT_NAME_REQUIRED
Name is empty after normalization.
400 DISCOUNT_NAME_TOO_LONG
Name exceeds the limit.
400 DISCOUNT_TYPE_INVALID
type is not a supported discount type.
400 DISCOUNT_ACTIVATION_INVALID
activation is not coupon or automatic.
400 DISCOUNT_CODE_REQUIRED
coupon activation without a code.
400 DISCOUNT_CODE_AUTOMATIC_FORBIDDEN
automatic activation with a code.
400 DISCOUNT_PRIORITY_RANGE
priority is outside the allowed range.
400 DISCOUNT_VALUE_RANGE
percentage value is not in (0, 100].
400 DISCOUNT_AMOUNTS_REQUIRED
fixed_amount without an amounts map.
400 DISCOUNT_CURRENCY_BASE_REQUIRED
A money map is missing the store's base currency entry.
400 DISCOUNT_CURRENCY_INVALID
A money map entry uses a currency not assigned to the market.
400 DISCOUNT_VALUE_FORBIDDEN
value sent for a type that doesn't take one.
400 DISCOUNT_AMOUNTS_FORBIDDEN
amounts sent for a type that doesn't take them.
400 DISCOUNT_BXGY_FIELDS_FORBIDDEN
BXGY fields sent for a non-BXGY type.
400 DISCOUNT_BXGY_BUY_REQUIRED
BXGY requires at least one valid buy item.
400 DISCOUNT_BXGY_GET_REQUIRED
BXGY requires at least one valid get item.
400 DISCOUNT_BUNDLE_FIELDS_FORBIDDEN
Bundle fields sent for a non-bundle type.
400 DISCOUNT_BUNDLE_MODE_REQUIRED
Bundle pricing mode is required.
400 DISCOUNT_BUNDLE_MODE_INVALID
Bundle pricing mode is not fixed_price or percentage.
400 DISCOUNT_BUNDLE_PRICE_REQUIRED
A fixed-price bundle is missing its currency price map.
400 DISCOUNT_BUNDLE_PERCENT_REQUIRED
A percentage bundle is missing a valid percentage.
400 DISCOUNT_BUNDLE_ITEMS_RANGE
Bundle component count is outside the limits response range.
400 DISCOUNT_BUNDLE_ITEM_DUPLICATE
The same product or variant appears more than once in the bundle.
400 DISCOUNT_BUNDLE_ITEM_QUANTITY
A bundle component quantity is outside the limits response range.
400 DISCOUNT_BUNDLE_MAX_SETS_RANGE
bundle_max_sets is outside the limits response range and is not unlimited.
400 DISCOUNT_MAX_DISCOUNT_FORBIDDEN
max_discount was sent for a type that does not support it.
400 DISCOUNT_ENTIRE_ORDER_ONLY
free_shipping, buy_x_get_y, or bundle with targeting other than entire_order.
400 DISCOUNT_APPLIES_TO_INVALID
applies_to is not a supported value.
400 DISCOUNT_TARGETS_REQUIRED
Specific targeting/eligibility without its ID list.
400 DISCOUNT_TARGETS_FORBIDDEN
An ID list sent for a non-matching targeting/eligibility.
400 DISCOUNT_ELIGIBILITY_INVALID
customer_eligibility is not a supported value.
400 DISCOUNT_MIN_QUANTITY_FORBIDDEN
min_quantity was sent for a discount type that does not support it.
400 DISCOUNT_USAGE_LIMIT_RANGE
usage_limit is outside the allowed range (and not -1).
400 DISCOUNT_PER_CUSTOMER_RANGE
per_customer_limit is outside the allowed range (and not -1).
400 MARKET_DISCOUNT_DATE_INVALID
ends_at is not after starts_at, or a date failed to parse.
400 MARKET_DISCOUNT_RELATION_LIMIT_REACHED
A relation list exceeds its per-discount cap.
400 MARKET_DISCOUNT_RELATION_DUPLICATE
A target or eligibility id appears more than once in its list.
404 MARKET_NOT_FOUND
Market does not exist in this store.
409 MARKET_DISCOUNT_CODE_DUPLICATE
A discount with this code already exists in the market (codes are case-insensitive).
409 MARKET_DISCOUNT_PRIORITY_DUPLICATE
A discount already occupies this priority slot in the market.
409 MARKET_DISCOUNT_LIMIT_REACHED
The market's discount cap has been reached.

Response

201

Sample response

{
  "success": true,
  "data": {
    "id": "7c4b1e2f-9a8d-4c3b-b2a1-0f9e8d7c6b5a",
    "store_id": "9a1f2c3d-4e5f-6789-abcd-ef0123456789",
    "market_id": "1c807b16-8a93-4f13-b998-1226c87d57ac",
    "name": "Summer sale",
    "type": "percentage",
    "activation": "coupon",
    "code": "SUMMER20",
    "status": "active",
    "priority": 10,
    "value": 20,
    "amounts": null,
    "applies_to": "entire_order",
    "exclude_sale_items": false,
    "min_subtotal": {"USD": "50.00"},
    "min_quantity": null,
    "max_discount": {"USD": "100.00"},
    "usage_limit": -1,
    "usage_count": 42,
    "per_customer_limit": 1,
    "customer_eligibility": "everyone",
    "first_order_only": false,
    "show_in_cart": true,
    "product_ids": [],
    "collection_ids": [],
    "category_ids": [],
    "customer_ids": [],
    "group_ids": [],
    "products": [],
    "collections": [],
    "categories": [],
    "customers": [],
    "groups": [],
    "bxgy_buy_items": [],
    "bxgy_get_items": [],
    "bundle_value_mode": null,
    "bundle_percentage": null,
    "bundle_prices": null,
    "bundle_max_sets": null,
    "bundle_items": [],
    "can_view_products": true,
    "can_view_customers": false,
    "starts_at": "Aug 1, 2026, 12:00 AM",
    "starts_at_iso": "2026-08-01T00:00:00",
    "ends_at": "Aug 31, 2026, 11:59 PM",
    "ends_at_iso": "2026-08-31T23:59:59",
    "created_at": "Jul 1, 2026, 10:15 AM",
    "updated_at": "Jul 9, 2026, 6:40 PM"
  }
}

Get a discount

GET read_markets

Fetch one discount with hydrated relations.

Returns the discount with its relation refs. Ref IDs always return; the hydrated LABELS (product titles, customer names and emails, group names) are other scopes' data and return only when the token also holds read_products (products/collections/categories/BXGY items) or read_customers (customers/groups) — the can_view_products/can_view_customers booleans in the response say which labels were redacted. status always reflects the current schedule.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`discountId` required	`string`	Discount id. Example: `7c4b1e2f-9a8d-4c3b-b2a1-0f9e8d7c6b5a`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

404 MARKET_NOT_FOUND
Market does not exist in this store.
404 MARKET_DISCOUNT_NOT_FOUND
Discount does not exist in this market.

Response

200

Sample response

{
  "success": true,
  "data": {
    "id": "7c4b1e2f-9a8d-4c3b-b2a1-0f9e8d7c6b5a",
    "store_id": "9a1f2c3d-4e5f-6789-abcd-ef0123456789",
    "market_id": "1c807b16-8a93-4f13-b998-1226c87d57ac",
    "name": "Summer sale",
    "type": "percentage",
    "activation": "coupon",
    "code": "SUMMER20",
    "status": "active",
    "priority": 10,
    "value": 20,
    "amounts": null,
    "applies_to": "entire_order",
    "exclude_sale_items": false,
    "min_subtotal": {"USD": "50.00"},
    "min_quantity": null,
    "max_discount": {"USD": "100.00"},
    "usage_limit": -1,
    "usage_count": 42,
    "per_customer_limit": 1,
    "customer_eligibility": "everyone",
    "first_order_only": false,
    "show_in_cart": true,
    "product_ids": [],
    "collection_ids": [],
    "category_ids": [],
    "customer_ids": [],
    "group_ids": [],
    "products": [],
    "collections": [],
    "categories": [],
    "customers": [],
    "groups": [],
    "bxgy_buy_items": [],
    "bxgy_get_items": [],
    "bundle_value_mode": null,
    "bundle_percentage": null,
    "bundle_prices": null,
    "bundle_max_sets": null,
    "bundle_items": [],
    "can_view_products": true,
    "can_view_customers": false,
    "starts_at": "Aug 1, 2026, 12:00 AM",
    "starts_at_iso": "2026-08-01T00:00:00",
    "ends_at": "Aug 31, 2026, 11:59 PM",
    "ends_at_iso": "2026-08-31T23:59:59",
    "created_at": "Jul 1, 2026, 10:15 AM",
    "updated_at": "Jul 9, 2026, 6:40 PM"
  }
}

Update a discount

PUT write_markets

Replace a discount's definition.

Full update — the same validation matrix as create runs against the complete new definition, and the relation lists replace the existing ones. A disabled discount stays disabled through updates (only the enable endpoint re-activates); otherwise the status follows the new schedule. Fires discounts/update.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`discountId` required	`string`	Discount id. Example: `7c4b1e2f-9a8d-4c3b-b2a1-0f9e8d7c6b5a`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`name` required	`string`	Discount name. Example: `Summer sale`
`type` required	`string`	`percentage`, `fixed_amount`, `free_shipping`, `buy_x_get_y`, or `bundle`. Each type requires exactly its own value fields and rejects the others'. Example: `percentage`
`activation` required	`string`	`coupon` (requires `code`) or `automatic` (rejects `code`). Example: `coupon`
`code`	`string`	Coupon code — required for `coupon` activation, unique per market case-insensitively, stored uppercased. Example: `SUMMER20`
`priority` required	`integer`	Evaluation priority — unique per market. Example: `10`
`value`	`number`	Percentage value (0–100] — `percentage` type only. Example: `20`
`amounts`	`object`	Currency-code → amount map — `fixed_amount` type only. The store's base currency entry is required; other entries must be market currencies. Example: `{"USD": "10.00", "EUR": "8.50"}`
`applies_to` required	`string`	`entire_order`, `specific_products`, `specific_collections`, or `specific_categories`. Free shipping, BXGY, and bundle discounts must be `entire_order`. Example: `entire_order`
`product_ids`	`array<integer>`	Target product ids — required exactly when applies_to is `specific_products`. Example: `[12, 34]`
`collection_ids`	`array<string>`	Target collection ids — required exactly when applies_to is `specific_collections`. Example: `["9a1f..."]`
`category_ids`	`array<integer>`	Target category ids — required exactly when applies_to is `specific_categories`. Example: `[7]`
`customer_eligibility` required	`string`	`everyone`, `specific_customers`, or `specific_segments`. Example: `everyone`
`customer_ids`	`array<string>`	Eligible customer ids — required exactly for `specific_customers`. Example: `["5b2e..."]`
`group_ids`	`array<string>`	Eligible customer-group ids — required exactly for `specific_segments`. Example: `["6c3f..."]`
`exclude_sale_items`	`boolean`	Skip items already on sale. Example: `false`
`min_subtotal`	`object`	Minimum order subtotal per currency (base currency entry required when set). Example: `{"USD": "50.00"}`
`min_quantity`	`integer`	Minimum order item count. Accepted only by discount types whose limits capability declares support. Example: `2`
`max_discount`	`object`	Cap on the computed discount per currency. Percentage type only. Example: `{"USD": "100.00"}`
`starts_at`	`string`	Schedule start in the store timezone, formatted as YYYY-MM-DDTHH:mm:ss with no timezone suffix. Status derives from the window. Example: `2026-08-01T00:00:00`
`ends_at`	`string`	Schedule end in the same store-local format — must be after starts_at. Example: `2026-08-31T23:59:59`
`usage_limit`	`integer`	Total redemption cap; -1 = unlimited. Example: `-1`
`per_customer_limit`	`integer`	Per-customer redemption cap; -1 = unlimited. Example: `1`
`first_order_only`	`boolean`	Restrict to a customer's first order. Example: `false`
`show_in_cart`	`boolean`	Surface a coupon in the cart before checkout. Automatic discounts reject this field when true. Example: `false`
`bxgy_buy_quantity`	`integer`	BXGY: quantity the buyer must add from the buy set. Example: `2`
`bxgy_get_quantity`	`integer`	BXGY: quantity granted from the get set. Example: `1`
`bxgy_get_type`	`string`	BXGY: `free`, `percentage` (requires bxgy_get_value in (0–100]), or `fixed` (requires a positive bxgy_get_value). Example: `free`
`bxgy_get_value`	`number`	BXGY: get-side value for `percentage`/`fixed` get types; forbidden for `free`. Example: `50`
`bxgy_max_uses`	`integer`	BXGY: how many times the pattern may apply per order. Example: `1`
`bxgy_buy_items`	`array<object>`	BXGY buy set: {item_type: product\|collection\|category, item_id} — no duplicates. Example: `[{"item_type": "product", "item_id": "12"}]`
`bxgy_get_items`	`array<object>`	BXGY get set — same shape as the buy set. Example: `[{"item_type": "product", "item_id": "34"}]`
`bundle_value_mode`	`string`	Bundle pricing mode: `fixed_price` or `percentage`. Example: `fixed_price`
`bundle_prices`	`object`	Bundle fixed set price by currency. Required for fixed_price mode and must include the store base currency. Example: `{"USD": "75.00"}`
`bundle_percentage`	`number`	Percentage off each complete component set. Required for percentage mode. Example: `15`
`bundle_max_sets`	`integer`	Maximum complete sets discounted per order; omit or use -1 for unlimited. Example: `2`
`bundle_items`	`array<object>`	Bundle components: 2–20 unique `{item_type: product\|variant, item_id, quantity}` rows. Every target must belong to the store. Example: `[{"item_type": "product", "item_id": "12", "quantity": 1}, {"item_type": "variant", "item_id": "45", "quantity": 2}]`

Errors

400 DISCOUNT_NAME_REQUIRED
Name is empty after normalization.
400 DISCOUNT_NAME_TOO_LONG
Name exceeds the limit.
400 DISCOUNT_TYPE_INVALID
type is not a supported discount type.
400 DISCOUNT_ACTIVATION_INVALID
activation is not coupon or automatic.
400 DISCOUNT_CODE_REQUIRED
coupon activation without a code.
400 DISCOUNT_CODE_AUTOMATIC_FORBIDDEN
automatic activation with a code.
400 DISCOUNT_PRIORITY_RANGE
priority is outside the allowed range.
400 DISCOUNT_VALUE_RANGE
percentage value is not in (0, 100].
400 DISCOUNT_AMOUNTS_REQUIRED
fixed_amount without an amounts map.
400 DISCOUNT_CURRENCY_BASE_REQUIRED
A money map is missing the store's base currency entry.
400 DISCOUNT_CURRENCY_INVALID
A money map entry uses a currency not assigned to the market.
400 DISCOUNT_VALUE_FORBIDDEN
value sent for a type that doesn't take one.
400 DISCOUNT_AMOUNTS_FORBIDDEN
amounts sent for a type that doesn't take them.
400 DISCOUNT_BXGY_FIELDS_FORBIDDEN
BXGY fields sent for a non-BXGY type.
400 DISCOUNT_BXGY_BUY_REQUIRED
BXGY requires at least one valid buy item.
400 DISCOUNT_BXGY_GET_REQUIRED
BXGY requires at least one valid get item.
400 DISCOUNT_BUNDLE_FIELDS_FORBIDDEN
Bundle fields sent for a non-bundle type.
400 DISCOUNT_BUNDLE_MODE_REQUIRED
Bundle pricing mode is required.
400 DISCOUNT_BUNDLE_MODE_INVALID
Bundle pricing mode is not fixed_price or percentage.
400 DISCOUNT_BUNDLE_PRICE_REQUIRED
A fixed-price bundle is missing its currency price map.
400 DISCOUNT_BUNDLE_PERCENT_REQUIRED
A percentage bundle is missing a valid percentage.
400 DISCOUNT_BUNDLE_ITEMS_RANGE
Bundle component count is outside the limits response range.
400 DISCOUNT_BUNDLE_ITEM_DUPLICATE
The same product or variant appears more than once in the bundle.
400 DISCOUNT_BUNDLE_ITEM_QUANTITY
A bundle component quantity is outside the limits response range.
400 DISCOUNT_BUNDLE_MAX_SETS_RANGE
bundle_max_sets is outside the limits response range and is not unlimited.
400 DISCOUNT_MAX_DISCOUNT_FORBIDDEN
max_discount was sent for a type that does not support it.
400 DISCOUNT_ENTIRE_ORDER_ONLY
free_shipping, buy_x_get_y, or bundle with targeting other than entire_order.
400 DISCOUNT_APPLIES_TO_INVALID
applies_to is not a supported value.
400 DISCOUNT_TARGETS_REQUIRED
Specific targeting/eligibility without its ID list.
400 DISCOUNT_TARGETS_FORBIDDEN
An ID list sent for a non-matching targeting/eligibility.
400 DISCOUNT_ELIGIBILITY_INVALID
customer_eligibility is not a supported value.
400 DISCOUNT_MIN_QUANTITY_FORBIDDEN
min_quantity was sent for a discount type that does not support it.
400 DISCOUNT_USAGE_LIMIT_RANGE
usage_limit is outside the allowed range (and not -1).
400 DISCOUNT_PER_CUSTOMER_RANGE
per_customer_limit is outside the allowed range (and not -1).
400 MARKET_DISCOUNT_DATE_INVALID
ends_at is not after starts_at, or a date failed to parse.
400 MARKET_DISCOUNT_RELATION_LIMIT_REACHED
A relation list exceeds its per-discount cap.
400 MARKET_DISCOUNT_RELATION_DUPLICATE
A target or eligibility id appears more than once in its list.
404 MARKET_NOT_FOUND
Market does not exist in this store.
409 MARKET_DISCOUNT_CODE_DUPLICATE
A discount with this code already exists in the market (codes are case-insensitive).
409 MARKET_DISCOUNT_PRIORITY_DUPLICATE
A discount already occupies this priority slot in the market.
409 MARKET_DISCOUNT_LIMIT_REACHED
The market's discount cap has been reached.
404 MARKET_DISCOUNT_NOT_FOUND
Discount does not exist in this market.

Response

200

Sample response

{
  "success": true,
  "data": {
    "id": "7c4b1e2f-9a8d-4c3b-b2a1-0f9e8d7c6b5a",
    "store_id": "9a1f2c3d-4e5f-6789-abcd-ef0123456789",
    "market_id": "1c807b16-8a93-4f13-b998-1226c87d57ac",
    "name": "Summer sale",
    "type": "percentage",
    "activation": "coupon",
    "code": "SUMMER20",
    "status": "active",
    "priority": 10,
    "value": 20,
    "amounts": null,
    "applies_to": "entire_order",
    "exclude_sale_items": false,
    "min_subtotal": {"USD": "50.00"},
    "min_quantity": null,
    "max_discount": {"USD": "100.00"},
    "usage_limit": -1,
    "usage_count": 42,
    "per_customer_limit": 1,
    "customer_eligibility": "everyone",
    "first_order_only": false,
    "show_in_cart": true,
    "product_ids": [],
    "collection_ids": [],
    "category_ids": [],
    "customer_ids": [],
    "group_ids": [],
    "products": [],
    "collections": [],
    "categories": [],
    "customers": [],
    "groups": [],
    "bxgy_buy_items": [],
    "bxgy_get_items": [],
    "bundle_value_mode": null,
    "bundle_percentage": null,
    "bundle_prices": null,
    "bundle_max_sets": null,
    "bundle_items": [],
    "can_view_products": true,
    "can_view_customers": false,
    "starts_at": "Aug 1, 2026, 12:00 AM",
    "starts_at_iso": "2026-08-01T00:00:00",
    "ends_at": "Aug 31, 2026, 11:59 PM",
    "ends_at_iso": "2026-08-31T23:59:59",
    "created_at": "Jul 1, 2026, 10:15 AM",
    "updated_at": "Jul 9, 2026, 6:40 PM"
  }
}

Delete a discount

DELETE write_markets

Delete a discount.

Deletes the discount together with its targeting, eligibility, BXGY item lists, and bundle component set. Usage history is retained for reporting. Fires discounts/delete.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`discountId` required	`string`	Discount id. Example: `7c4b1e2f-9a8d-4c3b-b2a1-0f9e8d7c6b5a`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

404 MARKET_NOT_FOUND
Market does not exist in this store.
404 MARKET_DISCOUNT_NOT_FOUND
Discount does not exist in this market.

Response

200

Sample response

{
  "success": true,
  "data": { "message": "Discount deleted." }
}

Enable a discount

POST write_markets

Re-enable a disabled discount.

Re-enables the discount. The resulting status follows the schedule — a discount whose window already passed comes back as expired, a future one as scheduled, otherwise active. Fires discounts/update.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`discountId` required	`string`	Discount id. Example: `7c4b1e2f-9a8d-4c3b-b2a1-0f9e8d7c6b5a`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 MARKET_DISCOUNT_STATUS_INVALID
Requested status is not enable/disable.
404 MARKET_NOT_FOUND
Market does not exist in this store.
404 MARKET_DISCOUNT_NOT_FOUND
Discount does not exist in this market.

Response

200

Sample response

{
  "success": true,
  "data": {
    "id": "7c4b1e2f-9a8d-4c3b-b2a1-0f9e8d7c6b5a",
    "store_id": "9a1f2c3d-4e5f-6789-abcd-ef0123456789",
    "market_id": "1c807b16-8a93-4f13-b998-1226c87d57ac",
    "name": "Summer sale",
    "type": "percentage",
    "activation": "coupon",
    "code": "SUMMER20",
    "status": "active",
    "priority": 10,
    "value": 20,
    "amounts": null,
    "applies_to": "entire_order",
    "exclude_sale_items": false,
    "min_subtotal": {"USD": "50.00"},
    "min_quantity": null,
    "max_discount": {"USD": "100.00"},
    "usage_limit": -1,
    "usage_count": 42,
    "per_customer_limit": 1,
    "customer_eligibility": "everyone",
    "first_order_only": false,
    "show_in_cart": true,
    "product_ids": [],
    "collection_ids": [],
    "category_ids": [],
    "customer_ids": [],
    "group_ids": [],
    "products": [],
    "collections": [],
    "categories": [],
    "customers": [],
    "groups": [],
    "bxgy_buy_items": [],
    "bxgy_get_items": [],
    "bundle_value_mode": null,
    "bundle_percentage": null,
    "bundle_prices": null,
    "bundle_max_sets": null,
    "bundle_items": [],
    "can_view_products": true,
    "can_view_customers": false,
    "starts_at": "Aug 1, 2026, 12:00 AM",
    "starts_at_iso": "2026-08-01T00:00:00",
    "ends_at": "Aug 31, 2026, 11:59 PM",
    "ends_at_iso": "2026-08-31T23:59:59",
    "created_at": "Jul 1, 2026, 10:15 AM",
    "updated_at": "Jul 9, 2026, 6:40 PM"
  }
}

Disable a discount

POST write_markets

Disable a discount.

Disables the discount. It stays disabled through schedule changes and updates until you enable it again. Fires discounts/update.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`discountId` required	`string`	Discount id. Example: `7c4b1e2f-9a8d-4c3b-b2a1-0f9e8d7c6b5a`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 MARKET_DISCOUNT_STATUS_INVALID
Requested status is not enable/disable.
404 MARKET_NOT_FOUND
Market does not exist in this store.
404 MARKET_DISCOUNT_NOT_FOUND
Discount does not exist in this market.

Response

200

Sample response

{
  "success": true,
  "data": {
    "id": "7c4b1e2f-9a8d-4c3b-b2a1-0f9e8d7c6b5a",
    "store_id": "9a1f2c3d-4e5f-6789-abcd-ef0123456789",
    "market_id": "1c807b16-8a93-4f13-b998-1226c87d57ac",
    "name": "Summer sale",
    "type": "percentage",
    "activation": "coupon",
    "code": "SUMMER20",
    "status": "active",
    "priority": 10,
    "value": 20,
    "amounts": null,
    "applies_to": "entire_order",
    "exclude_sale_items": false,
    "min_subtotal": {"USD": "50.00"},
    "min_quantity": null,
    "max_discount": {"USD": "100.00"},
    "usage_limit": -1,
    "usage_count": 42,
    "per_customer_limit": 1,
    "customer_eligibility": "everyone",
    "first_order_only": false,
    "show_in_cart": true,
    "product_ids": [],
    "collection_ids": [],
    "category_ids": [],
    "customer_ids": [],
    "group_ids": [],
    "products": [],
    "collections": [],
    "categories": [],
    "customers": [],
    "groups": [],
    "bxgy_buy_items": [],
    "bxgy_get_items": [],
    "bundle_value_mode": null,
    "bundle_percentage": null,
    "bundle_prices": null,
    "bundle_max_sets": null,
    "bundle_items": [],
    "can_view_products": true,
    "can_view_customers": false,
    "starts_at": "Aug 1, 2026, 12:00 AM",
    "starts_at_iso": "2026-08-01T00:00:00",
    "ends_at": "Aug 31, 2026, 11:59 PM",
    "ends_at_iso": "2026-08-31T23:59:59",
    "created_at": "Jul 1, 2026, 10:15 AM",
    "updated_at": "Jul 9, 2026, 6:40 PM"
  }
}

Get discount settings

GET read_markets

Fetch a market's discount-stacking settings.

Returns how discounts combine in this market. single applies one non-shipping discount; stack applies eligible automatic discounts and a coupon subset up to coupon_limit. At most one shipping discount applies, and it combines with a non-shipping result only when product_shipping_combine is enabled. priority_mode decides every forced choice. Markets without explicitly saved settings return the platform defaults. Allowed values and ranges return in limits.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

404 MARKET_NOT_FOUND
Market does not exist in this store.

Response

200

Sample response

{
  "success": true,
  "data": {
    "id": "3d2c1b0a-5e4f-6789-abcd-ef0123456789",
    "market_id": "1c807b16-8a93-4f13-b998-1226c87d57ac",
    "stacking_mode": "single",
    "priority_mode": "best_for_customer",
    "coupon_limit": 1,
    "auto_coupon_combine": true,
    "product_shipping_combine": true,
    "limits": {
      "stacking_modes": ["single", "stack"],
      "priority_modes": ["best_for_customer", "manual"],
      "coupon_limit_min": 1,
      "coupon_limit_max": 5
    }
  }
}

Update discount settings

PUT write_markets

Partially update a market's discount-stacking settings.

Atomically updates only the provided fields. Concurrent partial updates cannot replace unrelated fields. Values outside the sets and ranges in limits are rejected; coupon_limit can never exceed the platform maximum returned there. A request that changes no values emits no audit entry or webhook; a changed request fires discount_settings/update.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`stacking_mode`	`string`	`single` applies one non-shipping discount; `stack` applies eligible automatic discounts plus a bounded coupon subset. Example: `single`
`priority_mode`	`string`	`best_for_customer` ranks forced choices by savings; `manual` uses each discount's priority (lower number wins). Example: `best_for_customer`
`coupon_limit`	`integer`	Maximum coupon codes applied in stack mode. The priority mode chooses the subset at the limit; the platform cap comes from `limits`. Example: `1`
`auto_coupon_combine`	`boolean`	In stack mode, whether coupon codes can combine with automatic discounts. Example: `true`
`product_shipping_combine`	`boolean`	In either stacking mode, whether one shipping discount can combine with non-shipping discounts. Example: `true`

Errors

400 MARKET_STACKING_MODE_INVALID
stacking_mode is not single or stack.
400 MARKET_PRIORITY_MODE_INVALID
priority_mode is not best_for_customer or manual.
400 MARKET_COUPON_LIMIT_OUT_OF_RANGE
coupon_limit is outside 1..the platform cap.
404 MARKET_NOT_FOUND
Market does not exist in this store.

Response

200

Sample response

{
  "success": true,
  "data": {
    "id": "3d2c1b0a-5e4f-6789-abcd-ef0123456789",
    "market_id": "1c807b16-8a93-4f13-b998-1226c87d57ac",
    "stacking_mode": "single",
    "priority_mode": "best_for_customer",
    "coupon_limit": 1,
    "auto_coupon_combine": true,
    "product_shipping_combine": true,
    "limits": {
      "stacking_modes": ["single", "stack"],
      "priority_modes": ["best_for_customer", "manual"],
      "coupon_limit_min": 1,
      "coupon_limit_max": 5
    }
  }
}

Discount created

EVENT discounts/create write_markets markets:write

Fired when a discount is created in a market.

Payload fields

Field	Type	Description
`discount.id`	`string`	Always present
`discount.market_id`	`string`	Can be removed/added via the Payload builder
`discount.name`	`string`	Can be removed/added via the Payload builder
`discount.type`	`string`	Can be removed/added via the Payload builder
`discount.activation`	`string`	Can be removed/added via the Payload builder
`discount.code`	`string`	Can be removed/added via the Payload builder
`discount.status`	`string`	Can be removed/added via the Payload builder
`discount.priority`	`integer`	Can be removed/added via the Payload builder
`discount.value`	`number`	Can be removed/added via the Payload builder
`discount.amounts`	`object`	Can be removed/added via the Payload builder
`discount.applies_to`	`string`	Can be removed/added via the Payload builder
`discount.exclude_sale_items`	`boolean`	Can be removed/added via the Payload builder
`discount.min_subtotal`	`object`	Can be removed/added via the Payload builder
`discount.min_quantity`	`integer`	Can be removed/added via the Payload builder
`discount.max_discount`	`object`	Can be removed/added via the Payload builder
`discount.usage_limit`	`integer`	Can be removed/added via the Payload builder
`discount.usage_count`	`integer`	Can be removed/added via the Payload builder
`discount.per_customer_limit`	`integer`	Can be removed/added via the Payload builder
`discount.customer_eligibility`	`string`	Can be removed/added via the Payload builder
`discount.first_order_only`	`boolean`	Can be removed/added via the Payload builder
`discount.show_in_cart`	`boolean`	Can be removed/added via the Payload builder
`discount.bxgy_buy_quantity`	`integer`	Can be removed/added via the Payload builder
`discount.bxgy_get_quantity`	`integer`	Can be removed/added via the Payload builder
`discount.bxgy_get_type`	`string`	Can be removed/added via the Payload builder
`discount.bxgy_get_value`	`number`	Can be removed/added via the Payload builder
`discount.bxgy_max_uses`	`integer`	Can be removed/added via the Payload builder
`discount.bxgy_buy_items[*].item_type`	`string`	Can be removed/added via the Payload builder
`discount.bxgy_buy_items[*].item_id`	`string`	Can be removed/added via the Payload builder
`discount.bxgy_get_items[*].item_type`	`string`	Can be removed/added via the Payload builder
`discount.bxgy_get_items[*].item_id`	`string`	Can be removed/added via the Payload builder
`discount.bundle_value_mode`	`string`	Can be removed/added via the Payload builder
`discount.bundle_percentage`	`number`	Can be removed/added via the Payload builder
`discount.bundle_prices`	`object`	Can be removed/added via the Payload builder
`discount.bundle_max_sets`	`integer`	Can be removed/added via the Payload builder
`discount.bundle_items[*].item_type`	`string`	Can be removed/added via the Payload builder
`discount.bundle_items[*].item_id`	`string`	Can be removed/added via the Payload builder
`discount.bundle_items[*].quantity`	`integer`	Can be removed/added via the Payload builder
`discount.product_ids`	`array`	Can be removed/added via the Payload builder
`discount.collection_ids`	`array`	Can be removed/added via the Payload builder
`discount.category_ids`	`array`	Can be removed/added via the Payload builder
`discount.customer_ids`	`array`	Can be removed/added via the Payload builder
`discount.group_ids`	`array`	Can be removed/added via the Payload builder
`discount.starts_at`	`string`	Can be removed/added via the Payload builder
`discount.ends_at`	`string`	Can be removed/added via the Payload builder
`discount.created_at`	`string`	Can be removed/added via the Payload builder
`discount.updated_at`	`string`	Can be removed/added via the Payload builder

Payload shape

Sample payload

{
  "discount": {
    "activation": "...",
    "amounts": "...",
    "applies_to": "...",
    "bundle_items": [
      {
        "item_id": "...",
        "item_type": "...",
        "quantity": 0
      }
    ],
    "bundle_max_sets": null,
    "bundle_percentage": null,
    "bundle_prices": "...",
    "bundle_value_mode": null,
    "bxgy_buy_items": [
      {
        "item_id": "...",
        "item_type": "..."
      }
    ],
    "bxgy_buy_quantity": null,
    "bxgy_get_items": [
      {
        "item_id": "...",
        "item_type": "..."
      }
    ],
    "bxgy_get_quantity": null,
    "bxgy_get_type": null,
    "bxgy_get_value": null,
    "bxgy_max_uses": null,
    "category_ids": [],
    "code": null,
    "collection_ids": [],
    "created_at": "2026-06-09T12:00:00Z",
    "customer_eligibility": "...",
    "customer_ids": [],
    "ends_at": null,
    "exclude_sale_items": false,
    "first_order_only": false,
    "group_ids": [],
    "id": 7,
    "market_id": "...",
    "max_discount": "...",
    "min_quantity": null,
    "min_subtotal": "...",
    "name": "Acme",
    "per_customer_limit": null,
    "priority": 0,
    "product_ids": [],
    "show_in_cart": false,
    "starts_at": null,
    "status": "...",
    "type": "...",
    "updated_at": "2026-06-09T12:00:00Z",
    "usage_count": 0,
    "usage_limit": null,
    "value": null
  }
}

Discount updated

EVENT discounts/update write_markets markets:write

Fired when a discount changes — definition, targeting, schedule, limits, or enabled state.

Payload fields

Field	Type	Description
`discount.id`	`string`	Always present
`discount.market_id`	`string`	Can be removed/added via the Payload builder
`discount.name`	`string`	Can be removed/added via the Payload builder
`discount.type`	`string`	Can be removed/added via the Payload builder
`discount.activation`	`string`	Can be removed/added via the Payload builder
`discount.code`	`string`	Can be removed/added via the Payload builder
`discount.status`	`string`	Can be removed/added via the Payload builder
`discount.priority`	`integer`	Can be removed/added via the Payload builder
`discount.value`	`number`	Can be removed/added via the Payload builder
`discount.amounts`	`object`	Can be removed/added via the Payload builder
`discount.applies_to`	`string`	Can be removed/added via the Payload builder
`discount.exclude_sale_items`	`boolean`	Can be removed/added via the Payload builder
`discount.min_subtotal`	`object`	Can be removed/added via the Payload builder
`discount.min_quantity`	`integer`	Can be removed/added via the Payload builder
`discount.max_discount`	`object`	Can be removed/added via the Payload builder
`discount.usage_limit`	`integer`	Can be removed/added via the Payload builder
`discount.usage_count`	`integer`	Can be removed/added via the Payload builder
`discount.per_customer_limit`	`integer`	Can be removed/added via the Payload builder
`discount.customer_eligibility`	`string`	Can be removed/added via the Payload builder
`discount.first_order_only`	`boolean`	Can be removed/added via the Payload builder
`discount.show_in_cart`	`boolean`	Can be removed/added via the Payload builder
`discount.bxgy_buy_quantity`	`integer`	Can be removed/added via the Payload builder
`discount.bxgy_get_quantity`	`integer`	Can be removed/added via the Payload builder
`discount.bxgy_get_type`	`string`	Can be removed/added via the Payload builder
`discount.bxgy_get_value`	`number`	Can be removed/added via the Payload builder
`discount.bxgy_max_uses`	`integer`	Can be removed/added via the Payload builder
`discount.bxgy_buy_items[*].item_type`	`string`	Can be removed/added via the Payload builder
`discount.bxgy_buy_items[*].item_id`	`string`	Can be removed/added via the Payload builder
`discount.bxgy_get_items[*].item_type`	`string`	Can be removed/added via the Payload builder
`discount.bxgy_get_items[*].item_id`	`string`	Can be removed/added via the Payload builder
`discount.bundle_value_mode`	`string`	Can be removed/added via the Payload builder
`discount.bundle_percentage`	`number`	Can be removed/added via the Payload builder
`discount.bundle_prices`	`object`	Can be removed/added via the Payload builder
`discount.bundle_max_sets`	`integer`	Can be removed/added via the Payload builder
`discount.bundle_items[*].item_type`	`string`	Can be removed/added via the Payload builder
`discount.bundle_items[*].item_id`	`string`	Can be removed/added via the Payload builder
`discount.bundle_items[*].quantity`	`integer`	Can be removed/added via the Payload builder
`discount.product_ids`	`array`	Can be removed/added via the Payload builder
`discount.collection_ids`	`array`	Can be removed/added via the Payload builder
`discount.category_ids`	`array`	Can be removed/added via the Payload builder
`discount.customer_ids`	`array`	Can be removed/added via the Payload builder
`discount.group_ids`	`array`	Can be removed/added via the Payload builder
`discount.starts_at`	`string`	Can be removed/added via the Payload builder
`discount.ends_at`	`string`	Can be removed/added via the Payload builder
`discount.created_at`	`string`	Can be removed/added via the Payload builder
`discount.updated_at`	`string`	Can be removed/added via the Payload builder

Payload shape

Sample payload

{
  "discount": {
    "activation": "...",
    "amounts": "...",
    "applies_to": "...",
    "bundle_items": [
      {
        "item_id": "...",
        "item_type": "...",
        "quantity": 0
      }
    ],
    "bundle_max_sets": null,
    "bundle_percentage": null,
    "bundle_prices": "...",
    "bundle_value_mode": null,
    "bxgy_buy_items": [
      {
        "item_id": "...",
        "item_type": "..."
      }
    ],
    "bxgy_buy_quantity": null,
    "bxgy_get_items": [
      {
        "item_id": "...",
        "item_type": "..."
      }
    ],
    "bxgy_get_quantity": null,
    "bxgy_get_type": null,
    "bxgy_get_value": null,
    "bxgy_max_uses": null,
    "category_ids": [],
    "code": null,
    "collection_ids": [],
    "created_at": "2026-06-09T12:00:00Z",
    "customer_eligibility": "...",
    "customer_ids": [],
    "ends_at": null,
    "exclude_sale_items": false,
    "first_order_only": false,
    "group_ids": [],
    "id": 7,
    "market_id": "...",
    "max_discount": "...",
    "min_quantity": null,
    "min_subtotal": "...",
    "name": "Acme",
    "per_customer_limit": null,
    "priority": 0,
    "product_ids": [],
    "show_in_cart": false,
    "starts_at": null,
    "status": "...",
    "type": "...",
    "updated_at": "2026-06-09T12:00:00Z",
    "usage_count": 0,
    "usage_limit": null,
    "value": null
  }
}

Discount deleted

EVENT discounts/delete write_markets markets:write

Fired when a discount is deleted.

Payload fields

Field	Type	Description
`id`	`string`	Always present
`market_id`	`string`	Can be removed/added via the Payload builder
`name`	`string`	Can be removed/added via the Payload builder

Payload shape

Sample payload

{
  "id": 7,
  "market_id": "...",
  "name": "Acme"
}

Discount settings updated

EVENT discount_settings/update write_markets markets:write

Fired when a market's discount-stacking settings change.

Payload fields

Field	Type	Description
`discount_settings.market_id`	`string`	Always present
`discount_settings.stacking_mode`	`string`	Can be removed/added via the Payload builder
`discount_settings.priority_mode`	`string`	Can be removed/added via the Payload builder
`discount_settings.coupon_limit`	`integer`	Can be removed/added via the Payload builder
`discount_settings.auto_coupon_combine`	`boolean`	Can be removed/added via the Payload builder
`discount_settings.product_shipping_combine`	`boolean`	Can be removed/added via the Payload builder

Payload shape

Sample payload

{
  "discount_settings": {
    "auto_coupon_combine": false,
    "coupon_limit": 0,
    "market_id": "...",
    "priority_mode": "...",
    "product_shipping_combine": false,
    "stacking_mode": "..."
  }
}

Endpoints#

Path parameters

Headers

Errors

Path parameters

Query parameters

Headers

Errors

Path parameters

Headers

Body parameters

Errors

Path parameters

Headers

Errors

Path parameters

Headers

Body parameters

Errors

Path parameters

Headers

Errors

Path parameters

Headers

Errors

Path parameters

Headers

Errors

Path parameters

Headers

Errors

Path parameters

Headers

Body parameters

Errors

Webhook events#

Payload fields

Payload fields

Payload fields

Payload fields