Search API library /

Generate a test token to explore our APIs

Wix Coupons

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.

Coupons

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".

Coupon Object

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)

Examples

Example of Coupon Object

{
    "id": "91391e1b-22db-444d-9ce5-3df8dc12b9a8",
    "specification": {
      "name": "MoneyOff",
      "code": "test123",
      "startTime": "1550418287123",
      "limitedToOneItem": true,
      "active": true,
      "scope": {
        "namespace": "stores"
      },
      "moneyOffAmount": 52.0
    },
    "dateCreated": "1550418307500"
  }

Create a Coupon

Create a new coupon.

Permissions

The API requires COUPONS.MANAGE permission

POST

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

Request Headers

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

Body Params

NAME

TYPE

DESCRIPTION

specification

object

Coupon meta data. ID is ignored and created by the server

Status/Error Codes

The response will include an HTTP status code.

Response Object

NAME

TYPE

DESCRIPTION

id

string

ID of the created coupon, if the call is successful

Examples

Example of Create Coupon requests

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

Request

curl 'https://www.wixapis.com/stores/v2/coupons'
   --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}}}'
   -H 'Content-Type: application/json'
   -H 'Authorization: <AUTH>'

Response

{
    "id": "1758"
}


Create a "freeShipping" coupon that applies to to a minimum subtotal

Request

curl 'https://www.wixapis.com/stores/v2/coupons'
   --data-binary '{"specification":{"name":"FreeShipping","code":"ABC","active":true,"startTime":1554126275300,"minimumSubtotal":5,"limitedToOneItem":true,"freeShipping":true}}'
   -H 'Content-Type: application/json'
   -H 'Authorization: <AUTH>'

Response

{
    "id": "1759"
}

Delete a Coupon

Permissions

The API requires COUPONS.MANAGE permission

DELETE

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

Request Headers

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

Path Params

NAME

TYPE

DESCRIPTION

id

Required

string

ID of coupon to be deleted

Status/Error Codes

The response will include an HTTP status code.

Response Object

Returns an empty object.

Examples

Example of Delete Coupon request

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

Get a Coupon

Retrieve a coupon by ID

Permissions

The API requires COUPONS.MANAGE permission

GET

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

Request Headers

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

Path Params

NAME

TYPE

DESCRIPTION

id

Required

string

Coupon ID

Status/Error Codes

The response will include an HTTP status code.

Response Object

NAME

TYPE

DESCRIPTION

coupon

object

the returned coupon

Examples

Example of Get Coupon request

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

Query Coupons

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

Permissions

The API requires COUPONS.MANAGE permission

POST

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

Request Headers

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

Body Params

NAME

TYPE

DESCRIPTION

query

object

Status/Error Codes

The response will include an HTTP status code.

Response Object

NAME

TYPE

DESCRIPTION

coupons

array<object>

returned coupons

totalResults

integer

Examples

Example of Query Coupons request

Query all coupons, sorted by creation time

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

Update a Coupon

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

Permissions

The API requires COUPONS.MANAGE permission

PATCH

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

Request Headers

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

Path Params

NAME

TYPE

DESCRIPTION

id

Required

string

Body Params

NAME

TYPE

DESCRIPTION

fieldMask

object

field mask of fields to update. Valid field masks are

specification

object

code,name,startTime,expirationTime,usageLimit,behavior,scopes,minimumSubtotal,active the coupon meta data to change. changing the type is not allowed

Status/Error Codes

The response will include an HTTP status code.

Response Object

Returns an empty object.

Examples

Example of Update Coupon request

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