In This Article

Setup Coupons

Download skillThe skill is a reference md and part of wix-manage skill. You can use the following command to add the full wix-manage skill to your project:

Copy

Prerequisites

Wix Stores (or another eCommerce business solution) installed on the site

Required APIs

Create Coupon — POST /v2/coupons
Update Coupon — PATCH /v2/coupons/{id}
Query Coupons — POST /v2/coupons/query
Delete Coupon — DELETE /v2/coupons/{id}

Step 1: Query existing coupons

Before creating a coupon, check for code conflicts and existing promotions on the same scope.

Endpoint: POST https://www.wixapis.com/v2/coupons/query

Request:

Copy

Response:

Copy

Check for: duplicate codes, overlapping scopes with active coupons, and cross-mechanism stacking with active automatic discount rules.

Step 2: Create a percentage-off coupon

Endpoint: POST https://www.wixapis.com/v2/coupons

Request — 15% off all store products:

Copy

Response:

Copy

Request — 20% off a specific collection:

Copy

Request — 10% off a specific product:

Copy

Step 3: Create a fixed-amount coupon

Request — $10 off all products:

Copy

Step 4: Create a minimum subtotal coupon

Instead of targeting a scope, you can require a minimum cart subtotal. This is a oneOf with scope — you set EITHER scope OR minimumSubtotal, not both.

Request — 15% off orders over $100:

Copy

Key field rules

Field	Required	Notes
`name`	Yes	Display name shown to customers
`code`	Yes	Unique coupon code. Max 20 characters. Case-insensitive at checkout.
`startTime`	Yes	UNIX epoch in milliseconds (not seconds). E.g., `1714521600000` for 2024-05-01T00:00
`expirationTime`	No	UNIX epoch in milliseconds. Omit for no expiration.
`scope` OR `minimumSubtotal`	One required	OneOf — set scope to target items, OR minimumSubtotal for cart threshold. Cannot set both. Exception: freeShipping type ignores scope.
`usageLimit`	No	Total uses across all customers. Omit for unlimited.
`limitPerCustomer`	No	Max uses per customer. Omit for unlimited.
`limitedToOneItem`	No	If true, discount applies only to lowest-priced item when customer buys multiple.
`active`	No	Default `true`. Set `false` to create as draft.

Coupon types (oneOf — set exactly one)

Type	Field	Value	Example
Percentage off	`percentOffRate`	Double (e.g., `15` for 15%)	`"percentOffRate": 15`
Fixed amount off	`moneyOffAmount`	Double (e.g., `10` for $10 off)	`"moneyOffAmount": 10`
Fixed price	`fixedPriceAmount`	Double (e.g., `29.99`)	`"fixedPriceAmount": 29.99`
Free shipping	`freeShipping`	Boolean `true`	`"freeShipping": true`
Buy X Get Y	`buyXGetY`	Object with `x` and `y` fields	`"buyXGetY": {"x": 2, "y": 1}`

Scope values for Wix Stores

Scope target	`namespace`	`group.name`	`group.entityId`
All store products	`"stores"`	`"product"`	Omit (applies to all)
Specific product	`"stores"`	`"product"`	Product UUID
Specific collection	`"stores"`	`"collection"`	Collection UUID

Recommendation → Coupon API Mapping

When the recommendation output has mechanism: "COUPON", use this mapping to convert it into a Coupons API payload.

Scope mapping

Recommendation `scope`	Coupon `scope`
`SITE`	`{ "namespace": "stores", "group": { "name": "product" } }` (all products, no entityId)
`CATEGORY`	`{ "namespace": "stores", "group": { "name": "collection", "entityId": "<first categoryId>" } }`
`ITEMS`	`{ "namespace": "stores", "group": { "name": "product", "entityId": "<first productId>" } }`

Important limitation: The Coupons API scope supports only one entityId (one product or one collection). If the recommendation targets multiple products or categories:

For CATEGORY with multiple categoryIds: Create one coupon per collection, or pick the primary collection.
For ITEMS with multiple productIds: Create one coupon per product, or use minimumSubtotal instead of scope if the intent is cart-level.

Discount type mapping

Recommendation `discountType`	Coupon field
`PERCENTAGE`	`"percentOffRate": <value>`
`FIXED_AMOUNT`	`"moneyOffAmount": <value>`
`FIXED_PRICE`	`"fixedPriceAmount": <value>`

Condition mapping

Recommendation condition	Coupon approach
`minSubTotal > 0`	Use `minimumSubtotal` instead of `scope` (they are oneOf — cannot use both)
`minItemQuantity > 0`	Not natively supported by Coupons API. Mention in the coupon name (e.g., "Buy 3+, use code BUNDLE15") but the API cannot enforce item quantity.
`startDate`	Convert to UNIX epoch milliseconds: `Date.parse("2026-06-01") → 1748736000000`. Set as `startTime`.
`endDate`	Convert to UNIX epoch milliseconds. Set as `expirationTime`.

Code generation

Recommendation field	Coupon field	Rules
`code` from recommendation	`specification.code`	Max 20 characters. Must be unique on the site. Suggest memorable, brand-relevant codes (e.g., `SUMMER25`, `SAVE15`, `VIP20`).
`usageLimit` from recommendation	`specification.usageLimit`	Total times the coupon can be used. `0` in recommendation → omit (unlimited).
`limitPerCustomer` from recommendation	`specification.limitPerCustomer`	Max per customer. `0` → omit (unlimited). Recommend setting to `1` for most campaigns.

Full mapping example

Recommendation output:

Copy

Coupon API request:

Copy

Key differences from Automatic Discounts

Aspect	Automatic Discount (Discount Rules API)	Coupon (Coupons API)
Scope supports multiple items	Yes (multiple IDs in arrays)	No (one entityId per scope)
minSubTotal + scope together	Yes (scope + trigger)	No (oneOf — choose one)
minItemQuantity enforcement	Yes (ITEM_QUANTITY_RANGE trigger)	Not supported by API
Date format	ISO 8601 timestamps	UNIX epoch milliseconds
Created state	`active: false`, `status: PENDING`	`active: true` by default
Triggers/conditions	Separate trigger object with typed ranges	Only minimumSubtotal (simple threshold)

Error Handling

Error	Cause	Fix
Duplicate code	Another coupon uses the same code	Generate a different code
Invalid startTime	Value too low (must be epoch ms, not seconds)	Multiply by 1000 if in seconds
Both scope and minimumSubtotal set	These are oneOf — cannot use both	Choose scope OR minimumSubtotal
Code exceeds 20 characters	Code is too long	Shorten the code

References

Did this help?