Create coupon

post

https://{instance}.wshop.cloud/api/v1/coupon/create

Creates a coupon. The payload is validated like the back-office coupon form.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Request body to create a coupon. Fields not applicable to the chosen type are ignored.

label

string

required

The name of the coupon.

code

string

required

The code of the coupon. Must be unique.

type

string

enum

required

The type of the coupon.

format

object

required

The format of the coupon.

start_date

date

The date the coupon starts (YYYY-MM-DD). Required if format.type is permanent or single-use, ignored otherwise.

end_date

date

The date the coupon ends (YYYY-MM-DD), on or after start_date. Required if format.type is permanent or single-use, ignored otherwise.

min_order_amount

number

≥ 0

Defaults to 0

The minimum cart amount required to use the coupon. Applicable for: pct-discount, fixed-discount, free-shipping, free-selection-with-selection, shipping-pct-discount, cs-discount, dynamic-discount, multi-fixed-discount.

discount_value

number

The value of the coupon discount. Required for: pct-discount, fixed-discount, shipping-pct-discount, cs-discount, dynamic-discount.

max_eligible_products

integer

≥ 1

The maximum number of products in cart on which the coupon will be applied. Applicable for all types. Defaults to no maximum.

auto_applied

boolean

Defaults to false

When true, the coupon will be automatically added to the cart. Only one coupon can be automatically applied in the same period. Applicable for all types.

shipping_discount

object

The discount which will be applied to the shipping fees. Ignored for free-shipping and shipping-pct-discount.

apply_on_original_price

boolean

Defaults to false

When there is a commercial operation, the discount will be applied on the original selling price. Applicable for: pct-discount, fixed-discount, free-shipping, free-product-specific, free-selection-with-selection, shipping-pct-discount, dynamic-discount.

terms_and_conditions

string

The terms and conditions which will be displayed on the website. Applicable for all types.

audience

object

The audience targeted by the coupon.

apply_on_cheapest

boolean

Defaults to true

Apply the discount on the cheapest products first. Only applicable for nth-item-pct-off.

hide_on_website

boolean

Defaults to false

Hide the free products on the website. Only applicable for free-selection-with-selection.

qty_in_cart

integer

≥ 1

Quantity of products required in the cart. Required for: nth-item-pct-off, nth-item-fixed-price, free-selection-with-selection, buy-x-get-nth-fixed-price.

qty_free

integer

≥ 1

Quantity of free products. Required for free-selection-with-selection.

selection_free_shipping

string

enum

If shipping must be free for the free products, determines the carrier scope. Optional, for free-selection-with-selection only.

Allowed:

free_selection

object

Products from this selection will be free (up to qty_free items).

selling_price

number

> 0

The price the products will be sold at. Required for: nth-item-fixed-price, buy-x-get-nth-fixed-price.

pct_discount

number

> 0

The discount percentage applied to the products. Required for nth-item-pct-off.

up_to_x_times

integer

≥ 1

Repeat the discount up to X times. When omitted, the discount is not repeated. Applicable for: nth-item-fixed-price, nth-item-pct-off, buy-x-get-nth-fixed-price.

cumulable_tiers

boolean

Defaults to false

The tiers are cumulable. Only applicable for free-product-specific.

free_products

array of objects

length between 1 and 10

A list of free product tiers (up to 10). Required for free-product-specific.

free_products

tiers

array of objects

length between 1 and 4

A list of tiers (up to 4). Required for: buy-x-get-pct-off, auto-tiered-discount, spend-x-get-amount-off, spend-x-get-pct-off, buy-x-get-x-free, buy-x-get-amount-off.

tiers

product

array of objects

length ≥ 1

A list of products with their external reference, new selling price and optional label ID. Required for multi-fixed-discount.

product

eligible_countries

array of strings

required

length ≥ 1

A list of unique alpha-2 country ISO codes. The coupon will only work on the addresses of those countries.

eligible_countries*

eligible_carriers

array of integers

required

length ≥ 1

A list of unique, existing carrier IDs. The coupon will only work if the client chooses one of those carriers.

eligible_carriers*

product_selection

object

A selection of products. The coupon will only work on the products from this selection. product_selection or eligible_services is required for all types except free-product-specific and free-selection-with-selection; product_selection is always required for auto-tiered-discount.

cart_selection

object

A selection of products. The coupon will only work if the basket contains products from this selection. Required for: free-selection-with-selection, buy-x-get-nth-fixed-price.

discounted_selection

object

A selection of products. The discount will only be applied on the products from this selection. Required for buy-x-get-nth-fixed-price.

eligible_services

array of integers

length ≥ 1

A list of unique, existing service IDs of the site. eligible_services or product_selection is required for all types except free-product-specific and free-selection-with-selection.

eligible_services

site

integer

The site ID. Defaults to the main site. Applicable for all types.

Responses

200Result of the creation

400Bad Request — invalid or empty JSON body

401Unauthorized — invalid or expired token

403Forbidden — missing token, IP address different from the authentication request, or missing ACL right