Promo Codes
Many promo codes types are supported by the WSHOP API. Here are the datas you'll need to send to create them.
Promo codes types
The slug is to be used in the type field.
| Type | Slug |
|---|---|
| Percentage of reduction | pct-discount |
| Fixed discount | fixed-discount |
| Free shipping fees | free-shipping |
| Free specific product | free-product-specific |
| Buy X products, get a X% discount | buy-x-get-pct-off |
| Buy X amount, get X amount off | spend-x-get-amount-off |
| Buy X amount, get a X% discount | spend-x-get-pct-off |
| Buy X products, get X free products | buy-x-get-x-free |
| Nth item at X amount | nth-item-fixed-price |
| Nth item at X% discount | nth-item-pct-off |
| Free selection with selection | free-selection-with-selection |
| X% discount on shipping fees | shipping-pct-discount |
| Customer service discount | cs-discount |
| Dynamic discount | dynamic-discount |
| Multi fixed discount | multi-fixed-discount |
| Buy X products, the Xth product is at a fixed price | buy-x-get-nth-fixed-price |
Promo codes 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