Search.../
  1. Home
  2. Getting Started
  3. Overview
Generate a test token to explore our APIs

Wix Coupons

Guides

Additional information about this section

APIs
  • Coupons

    Let users create coupons that buyers can redeem on checkout

About Wix Coupons

Wix site owners can create coupons to provide their customers with discounts on the products on their site.
With the Coupons API, you can integrate with the site owner's coupon management in their Wix site to create, delete, get, check and query the site owner's coupons.

Important:
Wix site owners retain full access to their sites and may make changes that affect the viability of the coupons you create (e.g., deleting a product for which your platform has an active coupon). At the current time, there is no way to receive notifications about such changes.

Read more about managing Wix Coupons.

Was this helpful?

Coupons

Let users create coupons that buyers can redeem on checkout Learn more.

Guides

Additional information about this section

Main Entity

The API's main object

  • Coupon

    Coupon represents all information available for a coupon including its basic definition and runtime information

Endpoints

The endpoints exposed by this API

Coupon Types

Wix supports the following types of coupons:

  • $ discount - a.k.a. moneyOff, a fixed discount amount
  • % discount - a.k.a. percentOff, a discount as a % (e.g., 20% off)
  • Free Shipping - free shipping
  • Sale Price - a.k.a. fixedPrice, a fixed sale price
  • Buy X Get Y - get a certain number/kind of product for free (Y) when a customer buys a minimum number/kind of items (X). Both X and Y items must be in the customer's cart at time of purchase

Coupon Scope

Wix site owners can define the coupon to apply to a specific product, a collection of products, or to all of their products within a specific Wix Business Solution. When creating a coupon via API, you will need to apply a coupon scope.

Coupons are available for the following Wix business solutions:

  • Wix Stores
  • Wix Bookings
  • Wix Events

The scope should include:

  • Namespace - the relevant Wix Business Solution. Required.
  • Group - the relevant product/service type. Optional for most coupons - if not listed, the coupon will apply to all products/services/events in the namespace. Required for Wix Events event coupons.
  • Entity ID - the unique ID of the product/service the coupon applies to. Required for Wix Event event coupons, otherwise relevant only when Group is listed.

Wix Stores

NamespaceGroupEntity IDResult
storesN/AN/ACoupon applies to all products
storesproductproduct IDCoupon applies to the specific product with the provided ID
storescollectioncollection IDCoupon applies to the specific collection with the provided ID

Wix Bookings

NamespaceGroupEntity IDResult
bookingsN/AN/ACoupon applies to all services
bookingsserviceservice IDCoupon applies to the specific service with the provided ID

Wix Events

NamespaceGroupEntity IDResult
eventseventevent IDCoupon applies to the specific event with the provided ID
eventsticketN/ACoupon applies to all tickets
eventsticketticket IDCoupon applies to the specific ticket with the provided ID

Usage Limits

Coupons can be limited to:

  • 1 item per order
  • Minimum subtotal
  • X number of uses in total (all purchases by all customers, including repeat uses by the same customer)

Permissions

All the Coupons API endpoints require COUPONS.MANAGE permissions.

Coupon Functionality

  • Price discounts for collections apply to every item in that collection, no matter the item's price. If the coupon sets a $10 discount and there is an $8 item in that collection, that item will be free when a customer applies the coupon code.
  • Only 1 coupon can be applied per order. (It is, however, possible to offer free shipping above a set price along with another coupon.)
  • Coupon codes are case and space sensitive. (We recommend instructing customers to copy and paste the coupon code without making any changes.)
  • All discounts require a coupon.
  • Limit to 1 discount per order: If a customer buys multiple items that the coupon applies to, the discount is applied to the item with the lowest price.
  • Limited number of uses: You can set a limit for the number of times the coupon can be used in total, but you can't limit the number of times a specific customer can use the coupon.
  • If you or the Wix site owner created a coupon for a product, and then deletes that product, there is no notification that this product has a coupon attached to it.
  • Buy X Get Y:
    • Applies only to products in the user’s cart (e.g., to apply a buy 3 get 1 free coupon, the customer must add 4 of the relevant product(s) to their cart.
    • The defined scope for the coupon applies both to the product purchased and the product received for free (e.g., buy 3 of product X, the 4th is free, or buy 3 products from collection X, get the 4th for free).
  • Coupons can't be limited to a specific type/subset of customers (e.g., first-time or returning customers, customers from specific locales, etc.).
  • Wix Coupons does not send out a specific notification or provide analytics about when a coupon is used.
  • Coupons are not available for quantity based discounts in Wix Stores (e.g., if you buy 10 shirts, you get a 10% discount on the total price). However, you can add a quantity product option with a negative charge.
  • Gift card features are not available at this time.
  • There is no bulk upload capability for coupons.
  • There is no coupon code usage tracking available through Wix. It is possible to export the orders to a .CSV file.
  • Coupon currency can't be defined per coupon - $ discount coupons will be applied in any currency that the Wix site owner has set up in their Wix Business Manager settings.
  • Coupons for bookings scopes can't be applied to membership plans, or to services that are set to "Free/Prices Vary".

Was this helpful?

Coupon

Coupon represents all information available for a coupon including its basic definition and runtime information

Attributes

NAME
TYPE
DESCRIPTION
numberOfUsages

integer

How many times this coupon has been used

expired

boolean

Whether the coupon is expired

displayData

object

Display information for coupon applyTo

specification

object

the basic meta data of the coupon

id

string

Coupon ID (should not be passed on creation)

dateCreated

integer

Time the coupon was created (UNIX Epoch time in milliseconds)

Was this helpful?

Example of Coupon Object

Object

json

1{
2    "id": "91391e1b-22db-444d-9ce5-3df8dc12b9a8",
3    "specification": {
4      "name": "MoneyOff",
5      "code": "test123",
6      "startTime": "1550418287123",
7      "limitedToOneItem": true,
8      "active": true,
9      "scope": {
10        "namespace": "stores"
11      },
12      "moneyOffAmount": 52.0
13    },
14    "dateCreated": "1550418307500"
15  }

Create a Coupon

Create a new coupon.

Authorization

This API requires an authorization header - pass the access token from the OAuth installation flow.

Permissions

The API requires COUPONS.MANAGE

POST

https://www.wixapis.com/stores/v2/coupons

Body Params

NAME
TYPE
DESCRIPTION
CreateCouponRequest

object

Response Object

Create Coupon Response

NAME
TYPE
DESCRIPTION
id

string

ID of the created coupon, if the call is successful

Status/Error Codes

The response will include an HTTP status code.

Was this helpful?

Example of Create Coupon request

Create a "buyXGetY" coupon that applies to all Wix Stores products

Request

curl

Copy Code
1curl 'https://www.wixapis.com/stores/v2/coupons'
2   --data-binary '{"specification":{"name":"BuyXGetY","code":"ABC","active":true,"startTime":1554066000000,"usageLimit":10,"expirationTime":1554325199999,"scope":{"namespace":"stores"},"limitedToOneItem":true,"buyXGetY":{"x":3,"y":2}}}'
3   -H 'Content-Type: application/json'
4   -H 'Authorization: <AUTH>'
5

Response

json

1{
2    "id": "1758"
3}
4
Example 2

Get a Coupon

Retrieve a coupon by ID

Authorization

This API requires an authorization header - pass the access token from the OAuth installation flow.

Permissions

The API requires COUPONS.MANAGE

GET

https://www.wixapis.com/stores/v2/coupons/{id}

Path Params

NAME
TYPE
DESCRIPTION
id
Required

string

Coupon ID

Response Object

Get Coupon Response

NAME
TYPE
DESCRIPTION
coupon

object

the returned coupon

Status/Error Codes

The response will include an HTTP status code.

Was this helpful?

Example of Get Coupon request

Request

curl

Copy Code
1curl 'https://www.wixapis.com/stores/v2/coupons/{id}'
2   -H 'Authorization: <AUTH>'

Query Coupons

Query for coupons with pagination and filters. Max 100 coupons will be returned per request.

Authorization

This API requires an authorization header - pass the access token from the OAuth installation flow.

Permissions

The API requires COUPONS.MANAGE

POST

https://www.wixapis.com/stores/v2/coupons/query

Body Params

NAME
TYPE
DESCRIPTION
QueryCouponsRequest

object

Response Object

Query Coupons Response

NAME
TYPE
DESCRIPTION
coupons

Array<object>

returned coupons

totalResults

integer

Status/Error Codes

The response will include an HTTP status code.

Was this helpful?

Example of Query Coupons request

Query all coupons, sorted by creation time

Request

curl

Copy Code
1curl 'https://www.wixapis.com/stores/v2/coupons/query'
2   --data-binary '{"query":{"sort":"[{\"dateCreated\": \"asc\"}]"}}'
3   -H 'Content-Type: application/json'
4   -H 'Authorization: <AUTH>'

Update a Coupon

Update a coupon (coupon type can't be changed).

Authorization

This API requires an authorization header - pass the access token from the OAuth installation flow.

Permissions

The API requires COUPONS.MANAGE

PATCH

https://www.wixapis.com/stores/v2/coupons/{id}

Path Params

NAME
TYPE
DESCRIPTION
id
Required

string

Body Params

NAME
TYPE
DESCRIPTION
UpdateCouponRequest

object

Response Object

Update Coupon Response

Returns an empty object.

Status/Error Codes

The response will include an HTTP status code.

Was this helpful?

Example of Update Coupon request

Request

curl

Copy Code
1curl 'https://www.wixapis.com/stores/v2/coupons/{id}'
2   -X PATCH
3   --data-binary '{"specification":{"active":false},"fieldMask":{"paths":["active"]}}'
4   -H 'Content-Type: application/json'
5   -H 'Authorization: <AUTH>'

Delete a Coupon

Authorization

This API requires an authorization header - pass the access token from the OAuth installation flow.

Permissions

The API requires COUPONS.MANAGE

DELETE

https://www.wixapis.com/stores/v2/coupons/{id}

Path Params

NAME
TYPE
DESCRIPTION
id
Required

string

ID of coupon to be deleted

Response Object

Delete Coupon Response

Returns an empty object.

Status/Error Codes

The response will include an HTTP status code.

Was this helpful?

Example of Delete Coupon request

Request

curl

Copy Code
1curl 'https://www.wixapis.com/stores/v2/coupons/{id}'
2   -X DELETE
3   -H 'Authorization: <AUTH>'
)}