About the Coupons API

Wix site owners can create coupons to offer their customers discounts for products on their site.

With the Coupons API, you can manage a site's coupons.

Checking for Installed Apps

To use the Coupons API, the user's site must have a valid app installed. In the response to the Get App Instance endpoint, check the site.installedWixApps array for the following values:

  • stores
  • bookings
  • events
  • pricingPlans

Coupon Types

Wix supports the following types of coupons:

  • $ discount - a.k.a. moneyOffAmount, a fixed discount amount
  • % discount - a.k.a. percentOffAmount, 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 - purchase one or more of a specified product (X), and get one or more additional products (Y) for free. Both X and Y can be defined either as specified products or as a specified collection of products. All items must be in the customer's cart at time of purchase.

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)
Was this helpful?
Yes
No

Filter and sort

Query Language

Endpoints that allow querying follow these format guidelines.

Fields That Allow Filtering

FieldOperatorsSorting Allowed
id$eq,$ne,$hasSome,$contains,$startsWithAllowed
dateCreated$eq,$ne,$hasSome,$lt,$lte,$gt,$gteAllowed
expired$eq,$ne
specification.active$eq,$ne
specification.name$eq,$ne,$hasSome,$contains,$startsWithAllowed
specification.code$eq,$ne,$hasSome,$contains,$startsWithAllowed
specification.usageLimit$eq,$ne,$hasSome,$contains,$startsWithAllowed
specification.limitedToOneItem$eq,$ne
scope.namespace$eq,$ne,$hasSome,$contains,$startsWithAllowed
scope.group.name$eq,$ne,$hasSome,$contains,$startsWithAllowed
scope.group.entityId$eq,$ne,$hasSome,$contains,$startsWithAllowed

** Note that "HasSome" is same as the operator "IN" in SQL

Examples

Query valid (i.e., non-expired) coupons

Copy
1
curl 'https://www.wixapis.com/stores/v2/coupons/query' --data-binary '{"query":{"filter":"{\"expired\": false}"}}' -H 'Content-Type: application/json' -H 'Authorization: XXX'

Get all coupons, sorted by creation date

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

Get coupons by IDs

Copy
1
curl 'https://www.wixapis.com/stores/v2/coupons/query' --data-binary '{"query":{"filter":"{\"id\": {\"$hasSome\": [\"COUPON_ID_1\",\"COUPON_ID_2\"]}}"}}' -H 'Content-Type: application/json' -H 'Authorization: xxx'
Was this helpful?
Yes
No

Scope Values

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.

Coupons are available for the following Wix business solutions:

  • Wix Stores
  • Wix Bookings
  • Wix Events
  • Wix Pricing Plans

When creating a coupon via API, you will need to apply a coupon scope. The scope should include:

  • Namespace (required)
  • Group (optional - if not listed, the coupon will apply to all products/services/events in the namespace)
  • Entity ID - (required 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
eventseventN/ACoupon applies to all events
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

Wix Pricing Plans

NamespaceGroupEntity IDResult
pricingPlansN/AN/ACoupon applies to all pricing plans
pricingPlansplanplan IDCoupon applies to the specific pricing plan with the provided ID
Was this helpful?
Yes
No

Use Cases

Third party apps can use coupons to help site owners improve brand loyalty, increase customer engagement and incentivize customer purchases on Wix sites. Coupons can be set to activate and expire automatically, and to deactivate after a maximum amount of uses, so that the entire coupon lifecycle is set during creation. Coupons can also be changed both before they become active and while they are active, including deactivation, or deleted.

This article shares possible use cases your app could support, as well as an example flow that could support each use case. You're certainly not limited to what's on this page, but it can be a helpful jumping off point as you plan your app.

Create a "Buy X Get Y Free" coupon

This use case describes creating a coupon that grants an extra 2 entities (products/services/events/tickets) for free when the customer purchases 3 of the same entity at the regular price.
Coupon details include: coupon code: ABC, Active upon creation: true, Total usage limit: 10 uses, Valid from: April 1, 2019 12:00:00 AM, Valid until: April 3, 2019 11:59:59 PM.

  • If the coupon should apply to any product in Wix Stores, your request can look like this:

    Copy
    1
    {
    2
    "specification": {
    3
    "name": "BuyXGetY",
    4
    "code": "ABC",
    5
    "active": true,
    6
    "startTime": 1554066000000,
    7
    "usageLimit": 10,
    8
    "expirationTime": 1554325199999,
    9
    "scope": {
    10
    "namespace": "stores"
    11
    },
    12
    "limitedToOneItem": true,
    13
    "buyXGetY": {
    14
    "x": 3,
    15
    "y": 2
    16
    }
    17
    }
    18
    }
  • If the coupon should apply to a specific service in Wix Bookings, your request can look like this:

    Copy
    1
    {
    2
    "specification": {
    3
    "name": "BuyXGetY",
    4
    "code": "ABC",
    5
    "active": true,
    6
    "startTime": 1554066000000,
    7
    "usageLimit": 10,
    8
    "expirationTime": 1554325199999,
    9
    "scope": {
    10
    "namespace": "bookings",
    11
    "group": {
    12
    "name": "service",
    13
    "entityId": "e599b709-1a8b-478a-ae80-26192944aef5"
    14
    },
    15
    "limitedToOneItem": true,
    16
    "buyXGetY": {
    17
    "x": 3,
    18
    "y": 2
    19
    }
    20
    }
    21
    }
    22
    }
  • If the coupon should apply to all tickets in Wix Events, your request can look like this:

    Copy
    1
    {
    2
    "specification": {
    3
    "name": "BuyXGetY",
    4
    "code": "ABC",
    5
    "active": true,
    6
    "startTime": 1554066000000,
    7
    "usageLimit": 10,
    8
    "expirationTime": 1554325199999,
    9
    "scope": {
    10
    "namespace": "events",
    11
    "group": {
    12
    "name": "ticket"
    13
    }
    14
    },
    15
    "limitedToOneItem": true,
    16
    "buyXGetY": {
    17
    "x": 3,
    18
    "y": 2
    19
    }
    20
    }
    21
    }

Create an "X Amount Off a Purchase" coupon

This use case describes creating a coupon that grants a flat discount of 5 (currency is taken from the Wix site's settings) off a purchase.
Coupon details include: coupon code: ABC, Active upon creation: true, Total usage limit: 10 uses, Valid from: April 1, 2019 12:00:00 AM, Valid until: April 3, 2019 11:59:59 PM.

  • If the coupon should apply to all products in a specific Wix Stores collection, your request can look like this:

    Copy
    1
    {
    2
    "specification": {
    3
    "name": "Discount",
    4
    "code": "ABC",
    5
    "active": true,
    6
    "startTime": 1554126066895,
    7
    "usageLimit": 10,
    8
    "scope": {
    9
    "namespace": "stores",
    10
    "group": {
    11
    "name": "collection",
    12
    "entityId": "e599b709-1a8b-478a-ae80-26192944aef5"
    13
    }
    14
    },
    15
    "limitedToOneItem": false,
    16
    "moneyOffAmount": 5
    17
    }
    18
    }
  • If the coupon should apply to all services in Wix Bookings, your request can look like this:

    Copy
    1
    {
    2
    "specification": {
    3
    "name": "Discount",
    4
    "code": "ABC",
    5
    "active": true,
    6
    "startTime": 1554126066895,
    7
    "scope": {
    8
    "namespace": "bookings"
    9
    },
    10
    "limitedToOneItem": false,
    11
    "moneyOffAmount": 5
    12
    }
    13
    }
  • If the coupon should apply to a specific ticket in Wix Events, your request can look like this:

    Copy
    1
    {
    2
    "specification": {
    3
    "name": "Discount",
    4
    "code": "ABC",
    5
    "active": true,
    6
    "startTime": 1554126066895,
    7
    "scope": {
    8
    "namespace": "events",
    9
    "group": {
    10
    "name": "ticket",
    11
    "entityId": "e599b709-1a8b-478a-ae80-26192944aef5"
    12
    }
    13
    },
    14
    "limitedToOneItem": false,
    15
    "moneyOffAmount": 5
    16
    }
    17
    }

Create a "Fixed Discount" coupon

This use case describes creating a coupon that grants a special price of 5 (currency is taken from the Wix site's settings) to a specific entity (product/service/event/ticket).
Coupon details include: coupon code: ABC, Active upon creation: true, Total usage limit: 10 uses, Valid from: April 1, 2019 12:00:00 AM, Valid until: April 3, 2019 11:59:59 PM.

If the coupon should apply to a specific product in Wix Stores, your request can look like this:

Copy
1
{
2
"specification": {
3
"name": "SalePrice",
4
"code": "ABC",
5
"active": true,
6
"startTime": 1554126541151,
7
"scope": {
8
"namespace": "stores",
9
"group": {
10
"name": "product",
11
"entityId": "e599b709-1a8b-478a-ae80-26192944aef5"
12
}
13
},
14
"limitedToOneItem": true,
15
"fixedPriceAmount": 5
16
}
17
}

Create a "Percentage Discount" coupon

This use case describes creating a coupon that grants 5 percent off of a specific entity (product/service/event/ticket).
Coupon details include: coupon code: ABC, Active upon creation: true, Total usage limit: 10 uses, Valid from: April 1, 2019 12:00:00 AM.

  • If the coupon should apply to a specific collection in Wix Stores, your request can look like this:

    Copy
    1
    {
    2
    "specification": {
    3
    "name": "111",
    4
    "code": "ABC",
    5
    "active": true,
    6
    "startTime": 1554126716133,
    7
    "scope": {
    8
    "namespace": "stores",
    9
    "group": {
    10
    "name": "collection",
    11
    "entityId": "e599b709-1a8b-478a-ae80-26192944aef5"
    12
    }
    13
    },
    14
    "limitedToOneItem": true,
    15
    "percentOffRate": 5
    16
    }
    17
    }
  • If the coupon should apply to a specific ticket in Wix Events, your request can look like this:

    Copy
    1
    {
    2
    "specification": {
    3
    "name": "111",
    4
    "code": "ABC",
    5
    "active": true,
    6
    "startTime": 1554126716133,
    7
    "scope": {
    8
    "namespace": "events",
    9
    "group": {
    10
    "name": "ticket"
    11
    }
    12
    },
    13
    "limitedToOneItem": true,
    14
    "percentOffRate": 5
    15
    }
    16
    }

Create a "Free Shipping" coupon that applies to a minimum subtotal

This use case describes creating a coupon that grants free shipping to a purchase requiring shipping, when a minimum subtotal is reached.
Coupon details include: coupon code: ABC, Active upon creation: true, Total usage limit: 10 uses, Valid from: April 1, 2019 12:00:00 AM.

  • If the coupon should apply to all namespaces (stores, bookings, and events) with physical products that require shipping, your request can look like this:

    Copy
    1
    {
    2
    "specification": {
    3
    "name": "FreeShipping",
    4
    "code": "ABC",
    5
    "active": true,
    6
    "startTime": 1554126275300,
    7
    "minimumSubtotal": 5,
    8
    "limitedToOneItem": true,
    9
    "freeShipping": true
    10
    }
    11
    }
  • If the coupon should apply to all Wix Stores purchases with physical products that require shipping, your request can look like this:

    Copy
    1
    {
    2
    "specification": {
    3
    "name": "FreeShipping",
    4
    "code": "ABC",
    5
    "active": true,
    6
    "startTime": 1554126275300,
    7
    "scope": {
    8
    "namespace": "stores,"
    9
    },
    10
    "minimumSubtotal": 5,
    11
    "limitedToOneItem": true,
    12
    "freeShipping": true
    13
    }
    14
    }

Invalidate a coupon

This use case describes changing the coupon to make it inactive.

Copy
1
{
2
"specification": {
3
"active": false
4
},
5
"fieldMask": {
6
"paths": [
7
"active"
8
]
9
}
10
}

Delete a coupon

This use case describes deleting a coupon.

Copy
1
curl 'https://www.wixapis.com/stores/v2/coupons/<couponId>' \
2
-X DELETE \
3
-H 'Authorization: <AUTH>'
Was this helpful?
Yes
No

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.).
  • 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.
  • 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?
Yes
No

Coupon Object

Attributes
idstring
Coupon ID.

specificationobject
Basic coupon info.

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

expiredboolean
Whether the coupon is expired.

numberOfUsagesinteger
How many times this coupon has been used.

displayDataobject
Coupon display information.

appIdstringRead-onlyformat GUID
ID of the app that created the coupon. Empty if created by the site owner.
Was this helpful?
Yes
No

PostCreate A Coupon

Creates a new coupon.

When creating a coupon, the specification object must contain values for name, code, startTime, and either scope or minimumSubtotal. The exception is for a freeShipping coupon type, for which you cannot apply a scope and minimumSubtotal is optional.

The coupon scope defines the items a coupon applies to. A coupon can apply to all items in a specific Wix application, a group within the application, or a single item within a group. See valid scope values.

The specification object must also contain a value for exactly 1 of the following coupon properties. This defines the coupon type.

  • "moneyOffAmount"
  • "percentOffRate"
  • "freeShipping"
  • "fixedPriceAmount"
  • "buyXGetY"

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Coupons
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/stores/v2/coupons

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

GetGet A Coupon

Retrieves a coupon by ID.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Coupons
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/stores/v2/coupons/{id}

Was this helpful?
Yes
No

DeleteDelete A Coupon

Deletes a coupon.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Coupons
Learn more about permission scopes.
Endpoint
DELETE
https://www.wixapis.com/stores/v2/coupons/{id}

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PatchUpdate A Coupon

Updates a coupon.

Only the properties passed in the specification object will be updated. All other properties will remain the same.

To remove a value from the coupon, pass its corresponding property with a value of null.

When updating a coupon, you cannot change the coupon's type. For example, if the coupon's type is moneyOffAmount, you cannot change it to fixedPriceAmount. You can update the coupon type's value. For example, you can change the value of moneyOffAmount from 5 to 10.

The coupon scope defines the items a coupon applies to. A coupon can apply to all items in a specific Wix application, a group within the application, or a single item within a group. See valid scope values.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Coupons
Learn more about permission scopes.
Endpoint
PATCH
https://www.wixapis.com/stores/v2/coupons/{id}

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostQuery Coupons

Retrieves a list of coupons with pagination and filters. A maximum of 100 coupons will be returned per request.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Coupons
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/stores/v2/coupons/query

Was this helpful?
Yes
No

PostBulk Delete Coupons

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Deletes multiple coupons.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Coupons
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/stores/v2/bulk/coupons/delete

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostBulk Create Coupons

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Creates multiple coupons.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Coupons
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/stores/v2/bulk/coupons/create

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

Coupon Created

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a coupon is created.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.ecommerce.coupons.v2.coupon.

slugstring
Event name. Expected created.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

createdEventobject
Event information.
Was this helpful?
Yes
No

Coupon Updated

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a coupon specification is updated.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.ecommerce.coupons.v2.coupon.

slugstring
Event name. Expected updated.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

updatedEventobject
Event information.
Was this helpful?
Yes
No

Coupon Deleted

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a coupon is deleted.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.ecommerce.coupons.v2.coupon.

slugstring
Event name. Expected deleted.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

deletedEventstruct
Event information.
Was this helpful?
Yes
No

Coupon Applied

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a coupon is applied.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.ecommerce.coupons.v2.coupon.

slugstring
Event name. Expected applied.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

actionEventobject
Event information.
Was this helpful?
Yes
No