Coupon fields
| Field | Data Type | Mandatory | For promo code types | Accepted Values | Default Value | Description | Example |
|---|---|---|---|---|---|---|---|
label | string | ✅ | All | The name of the promo code | |||
code | string | ✅ | All | The code of the promo code | |||
type | enum | ✅ | All | pct-discount, fixed-discount, free-shipping, free-product-specific, buy-x-get-pct-off, spend-x-get-amount-off, spend-x-get-pct-off, buy-x-get-x-free, nth-item-fixed-price, nth-item-pct-off, free-selection-with-selection, shipping-pct-discount, cs-discount, dynamic-discount, multi-fixed-discount, buy-x-get-nth-fixed-price, auto-tiered-discount, buy-x-get-amount-off | The type of the promo code | ||
format | object | ✅ | All | The format of the promo code | |||
format.type | enum | ✅ | All | permanent, single-use, first-order, first-order-service, first-order-product | The format type | ||
format.unlimited_usage | boolean | ️ ⚠️ | All | The promo code can be used an infinite number of times. Required if format.type is permanent | |||
format.max_usage_count | integer | ⚠️ | All | The number of times the promo code can be used. Required if format.type is permanent and format.unlimited_usage is false | |||
start_date | date | ⚠️ | All | YYYY-MM-DD | The date the promo code starts. Required if format.type is either permanent or single-use | 2026-04-24 | |
end_date | date | ⚠️ | All | YYYY-MM-DD | The date the promo code ends. Required if format.type is either permanent or single-use | 2026-04-24 | |
min_order_amount | float | ❌️ | pct-discount, fixed-discount, free-shipping, free-selection-with-selection, shipping-pct-discount,cs-discount, dynamic-discount, multi-fixed-discount | 0 | The minimum amount in cart required to use the promo code | ||
discount_value | integer | ✅ | pct-discount, fixed-discount, shipping-pct-discount, cs-discount, dynamic-discount | The value of the promo code' discount | |||
max_eligible_products | integer | ❌️ | All | No maximum | The maximum number of products in cart on which the promo code will be applied. | ||
auto_applied | boolean | ❌️ | All | false | When true, the promo code will be automatically added to the cart. Only one coupon can be automatically added to the cart in the same period | ||
shipping_discount | object | ❌️ | pct-discount, fixed-discount, free-product-specific, buy-x-get-pct-off, spend-x-get-amount-off, spend-x-get-pct-off, buy-x-get-x-free, nth-item-fixed-price, nth-item-pct-off, free-selection-with-selection, cs-discount, dynamic-discount, multi-fixed-discount, buy-x-get-nth-fixed-price, auto-tiered-discount, buy-x-get-amount-off | No discount | The discount which will be applied to the shipping fees | ||
shipping_discount.enable | boolean | ⚠️ | pct-discount, fixed-discount, free-product-specific, buy-x-get-pct-off, spend-x-get-amount-off, spend-x-get-pct-off, buy-x-get-x-free, nth-item-fixed-price, nth-item-pct-off, free-selection-with-selection, cs-discount, dynamic-discount, multi-fixed-discount, buy-x-get-nth-fixed-price, auto-tiered-discount, buy-x-get-amount-off | Enabling the discount which will be applied to the shipping fees. Required when shipping_discount is present | |||
shipping_discount.discount_value | float | ❌️ | pct-discount, fixed-discount, free-product-specific, buy-x-get-pct-off, spend-x-get-amount-off, spend-x-get-pct-off, buy-x-get-x-free, nth-item-fixed-price, nth-item-pct-off, free-selection-with-selection, cs-discount, dynamic-discount, multi-fixed-discount, buy-x-get-nth-fixed-price, auto-tiered-discount, buy-x-get-amount-off | No paid shipping fees | The value discount which will be applied to the shipping fees. It is a fixed amount. | ||
shipping_discount.carrier_scope | enum | ⚠️ | pct-discount, fixed-discount, free-product-specific, buy-x-get-pct-off, spend-x-get-amount-off, spend-x-get-pct-off, buy-x-get-x-free, nth-item-fixed-price, nth-item-pct-off, free-selection-with-selection, cs-discount, dynamic-discount, multi-fixed-discount, buy-x-get-nth-fixed-price, auto-tiered-discount, buy-x-get-amount-off | all, standard-and-relay, standard, relay, large-item | The scope of the discount which will be applied to the shipping fees. Required if shipping_discount.enable is true | ||
apply_on_original_price | boolean | ❌️ | pct-discount, fixed-discount, free-shipping, free-product-specific, free-selection-with-selection, shipping-pct-discount, dynamic-discount | false | When there is a commercial operation, the discount will be applied on the original selling price | ||
terms_and_conditions | string | ❌️ | All | The terms and conditions which will be displayed on the website | |||
audience | object | ❌️ | All | The audience targeted by the promo code | |||
audience.scope | enum | ⚠️ | All | all, email, newsletter-id, client-id | The scope of the audience. Required when audienceis present | ||
audience.emails | array | ⚠️ | All | A list of email addresses. Required when audience.scope is email | ['[email protected]', '[email protected]'] | ||
audience.newsletter_ids | array | ⚠️ | All | A list of newsletter IDs. Required when audience.scope is newsletter-id | [12,58] | ||
audience.client_ids | array | ⚠️ | All | A list of client IDs. Required when audience.scope is client-id | |||
audience.send_alert_mail | boolean | ❌ | fixed-discount | false | Send an alert mail to the audience | ||
audience.send_reclamation_mail | boolean | ❌ | multi-fixed-discount | false | Send a reclamation mail (C5) to the audience | ||
audience.send_replacement_mail | boolean | ❌ | multi-fixed-discount | false | Send a replacement mail (C2, C3, C4) to the audience | ||
apply_on_cheapest | boolean | ❌ | nth-item-pct-off | true | Apply the promo code on the cheapest products first | ||
hide_on_website | boolean | ❌ | free-selection-with-selection | true | The tiers are cumulable | ||
qty_in_cart | integer | ✅ | nth-item-pct-off, nth-item-fixed-price, free-selection-with-selection, buy-x-get-nth-fixed-price | Quantity of products in cart | |||
qty_free | integer | ✅ | free-selection-with-selection | Quantity of free products | |||
selection_free_shipping | enum | ❌ | free-selection-with-selection | all, standard-and-relay, standard, relay, large-item | No free shipping fees for the free products | If the shipping must be free for the free products, determines the scope | |
free_selection | object | ✅ | free-selection-with-selection | qty_free products from this selection will be free | |||
free_selection.mode | enum | ⚠️ | free-selection-with-selection | department, sub_category, product, carrier | The selection mode. basket means the promo code will be applied to the whole basket, service means the promo code will be applied on the services only | ||
free_selection.carriers | enum | ⚠️ | free-selection-with-selection | all, standard-and-relay, large-item | The carrier scope. Required if product_selection.mode is carrier | ||
free_selection.departments | array | ⚠️ | free-selection-with-selection | A list of department IDs. Required if product_selection.mode is department | |||
free_selection.sub_categories | array | ⚠️ | free-selection-with-selection | A list of sub-category IDs. Required if product_selection.mode is sub-category | |||
free_selection.products | array | ⚠️ | free-selection-with-selection | A list of products internal references. Required if product_selection.mode is product | ["01W000125","01W000418"] | ||
selling_price | float | ✅ | nth-item-fixed-price, buy-x-get-nth-fixed-price | The price the products will be sold | |||
pct_discount | float | ✅ | nth-item-pct-off | The discount percentage applied to the products | |||
up_to_x_times | integer | ❌ | nth-item-fixed-price, nth-item-pct-off, buy-x-get-nth-fixed-price | 1 | Repeat the discount up to X times | ||
cumulable_tiers | boolean | ❌ | free-product-specific | true | The tiers are cumulable | ||
free_products | array | ✅ | free-product-specific | true | A list of free products | ||
free_products[].condition | float | ✅ | free-product-specific | true | The minium amount for the free product to be added to the client's basket | ||
free_products[].products | array | ✅ | free-product-specific | true | A list of products that can be free. The first product of this list with enough inventory left will be added to the basket | ||
free_products[].products[].reference | string | ✅ | free-product-specific | true | The internal reference of the product | ||
free_products[].products[].hide | boolean | ✅ | free-product-specific | true | Hide this product on the website while the promo code is active | ||
tiers | array | ✅ | auto-tiered-discount, spend-x-get-amount-off, spend-x-get-pct-off, buy-x-get-x-free, buy-x-cart-get-pct-off, buy-x-get-amount-off | A list of tiers (up to 4) | |||
tiers[].condition | numeric | ✅ | auto-tiered-discount, spend-x-get-amount-off, spend-x-get-pct-off, buy-x-get-x-free, buy-x-cart-get-pct-off, buy-x-get-amount-off | The condition needed for the tier to be applied. Value for spend-x-get-amount-off, spend-x-get-pct-off is a float, integer otherwise | |||
tiers[].value | numeric | ✅ | auto-tiered-discount, spend-x-get-amount-off, spend-x-get-pct-off, buy-x-get-x-free, buy-x-cart-get-pct-off, buy-x-get-amount-off | The value applied for the tier. It must be a integer for buy-x-get-x-free, float otherwise | |||
product | array | ✅ | multi-fixed-discount | A list of products with their external reference, new selling price and label ID | |||
product[].external_reference | string | ✅ | multi-fixed-discount | The external reference of the product | |||
product[].price | numeric | ✅ | multi-fixed-discount | The new selling price | |||
product[].label | integer | ❌ | multi-fixed-discount | The ID of the label which will be displayed on the product | |||
eligible_countries | array | ✅ | All | A list of alpha-2 country ISO codes. The promo code will only work on the addresses of those countries | ["FR", "BE"] | ||
eligible_carriers | array | ✅ | All | A list of carrier IDs. The promo code will only work if the client chooses one of those carriers | |||
product_selection | object | ⚠️ | pct-discount, fixed-discount, buy-x-get-pct-off, spend-x-get-amount-off, spend-x-get-pct-off, buy-x-get-x-free, nth-item-fixed-price, nth-item-pct-off, cs-discount, dynamic-discount,auto-tiered-discount | A selection of products. The promo code will only work on the products from this selection. Required when eligible_services is not present | |||
product_selection.mode | enum | ⚠️ | pct-discount, fixed-discount, buy-x-get-pct-off, spend-x-get-amount-off, spend-x-get-pct-off, buy-x-get-x-free, nth-item-fixed-price, nth-item-pct-off, cs-discount, dynamic-discount,auto-tiered-discount | basket, department, super-category, category, sub_category, brand, product for types pct-discount, fixed-discount, free-shipping, nth-item-fixed-price, nth-item-pct-off, shipping-pct-discount, cs-discount, dynamic-discount, basket, department, super-category, category, sub_category, brand, product, service for type free-selection-with-selection,buy-x-get-nth-fixed-price, multi-fixed-discount, and department, product, carrier for types buy-x-get-pct-off, spend-x-get-amount-off, spend-x-get-pct-off, buy-x-get-x-free, auto-tiered-discount, buy-x-get-amount-off | The selection mode. basket means the promo code will be applied to the whole basket, service means the promo code will be applied on the services only | ||
product_selection.super_categories | array | ⚠️ | pct-discount, fixed-discount, free-shipping, nth-item-fixed-price, nth-item-pct-off, free-selection-with-selection, shipping-pct-discount, cs-discount, dynamic-discount, buy-x-get-nth-fixed-price, multi-fixed-discount | A list of super category IDs. Required if product_selection.mode is super-category | |||
product_selection.carriers | enum | ⚠️ | buy-x-get-pct-off, spend-x-get-amount-off, spend-x-get-pct-off, buy-x-get-x-free, auto-tiered-discount, buy-x-get-amount-off | all, standard-and-relay, large-item | The carrier scope. Required if product_selection.mode is carrier | ||
product_selection.categories | array | ⚠️ | pct-discount, fixed-discount, free-shipping, nth-item-fixed-price, nth-item-pct-off, free-selection-with-selection, shipping-pct-discount, cs-discount, dynamic-discount, buy-x-get-nth-fixed-price, multi-fixed-discount | A list of category IDs. Required if product_selection.mode is category | |||
product_selection.departments | array | ⚠️ | pct-discount, fixed-discount, buy-x-get-pct-off, spend-x-get-amount-off, spend-x-get-pct-off, buy-x-get-x-free, nth-item-fixed-price, nth-item-pct-off, cs-discount, dynamic-discount,auto-tiered-discount | A list of department IDs. Required if product_selection.mode is department | |||
product_selection.sub_categories | array | ⚠️ | pct-discount, fixed-discount, free-shipping, nth-item-fixed-price, nth-item-pct-off, free-selection-with-selection, shipping-pct-discount, cs-discount, dynamic-discount, buy-x-get-nth-fixed-price, multi-fixed-discount | A list of sub-category IDs. Required if product_selection.mode is sub-category | |||
product_selection.brands | array | ⚠️ | pct-discount, fixed-discount, free-shipping, nth-item-fixed-price, nth-item-pct-off, free-selection-with-selection, shipping-pct-discount, cs-discount, dynamic-discount, buy-x-get-nth-fixed-price, multi-fixed-discount | A list of brand IDs. Required if product_selection.mode is brand | |||
product_selection.products | array | ⚠️ | pct-discount, fixed-discount, buy-x-get-pct-off, spend-x-get-amount-off, spend-x-get-pct-off, buy-x-get-x-free, nth-item-fixed-price, nth-item-pct-off, cs-discount, dynamic-discount,auto-tiered-discount | A list of products internal references. Required if product_selection.mode is product | ["01W000125","01W000418"] | ||
cart_selection | object | ✅️ | free-selection-with-selection, buy-x-get-nth-fixed-price | A selection of products. The promo code will only work if the basket has some of the products from this selection | |||
cart_selection.mode | enum | ️✅️ | free-selection-with-selection, buy-x-get-nth-fixed-price | basket, department, super-category, category, sub_category, brand, product for types pct-discount, fixed-discount, free-shipping, nth-item-fixed-price, nth-item-pct-off, shipping-pct-discount, cs-discount, dynamic-discount, basket, department, super-category, category, sub_category, brand, product, service for type free-selection-with-selection,buy-x-get-nth-fixed-price, multi-fixed-discount, and department, product, carrier for types buy-x-get-pct-off, spend-x-get-amount-off, spend-x-get-pct-off, buy-x-get-x-free, auto-tiered-discount, buy-x-get-amount-off | The selection mode. basket means the promo code will work on the whole basket, service means the promo code will be applied on the services only | ||
cart_selection.super_categories | array | ⚠️ | free-selection-with-selection, buy-x-get-nth-fixed-price | A list of super category IDs. Required if product_selection.mode is super-category | |||
cart_selection.carriers | enum | ⚠️ | free-selection-with-selection, buy-x-get-nth-fixed-price | all, standard-and-relay, large-item | The carrier scope. Required if product_selection.mode is carrier | ||
cart_selection.categories | array | ⚠️ | free-selection-with-selection, buy-x-get-nth-fixed-price | A list of category IDs. Required if product_selection.mode is category | |||
cart_selection.departments | array | ⚠️ | free-selection-with-selection, buy-x-get-nth-fixed-price | A list of department IDs. Required if product_selection.mode is department | |||
cart_selection.sub_categories | array | ⚠️ | free-selection-with-selection, buy-x-get-nth-fixed-price | A list of sub-category IDs. Required if product_selection.mode is sub-category | |||
cart_selection.brands | array | ⚠️ | free-selection-with-selection, buy-x-get-nth-fixed-price | A list of brand IDs. Required if product_selection.mode is brand | |||
cart_selection.products | array | ⚠️ | free-selection-with-selection, buy-x-get-nth-fixed-price | A list of products internal references. Required if product_selection.mode is product | ["01W000125","01W000418"] | ||
discounted_selection | object | ✅️ | buy-x-get-nth-fixed-price | A selection of products. The promo code will only be applied on the products from this selection | |||
discounted_selection.mode | enum | ⚠️ | free-selection-with-selection | department, sub_category, product, carrier | The selection mode. basket means the promo code will be applied to the whole basket, service means the promo code will be applied on the services only | ||
discounted_selection.carriers | enum | ⚠️ | free-selection-with-selection | all, standard-and-relay, large-item | The carrier scope. Required if product_selection.mode is carrier | ||
discounted_selection.departments | array | ⚠️ | free-selection-with-selection | A list of department IDs. Required if product_selection.mode is department | |||
discounted_selection.sub_categories | array | ⚠️ | free-selection-with-selection | A list of sub-category IDs. Required if product_selection.mode is sub-category | |||
discounted_selection.products | array | ⚠️ | free-selection-with-selection | A list of products internal references. Required if product_selection.mode is product | ["01W000125","01W000418"] | ||
eligible_services | array | ⚠️ | pct-discount,fixed-discount,free-shipping,free-product-specific,buy-x-get-pct-off,spend-x-get-amount-off,spend-x-get-pct-off,buy-x-get-x-free,nth-item-fixed-price,nth-item-pct-off,dynamic-discount,multi-fixed-discount,buy-x-get-nth-fixed-price,auto-tiered-discount | A list of service IDs. Required if product_selection is not present | |||
site | integer | ❌️ | All | 1 | The site ID |
Updated about 1 month ago