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.

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

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.

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)

Endpoints that allow querying follow these format guidelines.

Field	Operators	Sorting Allowed
id	$eq,$ne,$hasSome,$contains,$startsWith	Allowed
dateCreated	$eq,$ne,$hasSome,$lt,$lte,$gt,$gte	Allowed
expired	$eq,$ne
specification.active	$eq,$ne
specification.name	$eq,$ne,$hasSome,$contains,$startsWith	Allowed
specification.code	$eq,$ne,$hasSome,$contains,$startsWith	Allowed
specification.usageLimit	$eq,$ne,$hasSome,$contains,$startsWith	Allowed
specification.limitedToOneItem	$eq,$ne
scope.namespace	$eq,$ne,$hasSome,$contains,$startsWith	Allowed
scope.group.name	$eq,$ne,$hasSome,$contains,$startsWith	Allowed
scope.group.entityId	$eq,$ne,$hasSome,$contains,$startsWith	Allowed

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

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

Copy Code
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 Code
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 Code
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'

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)

Namespace	Group	Entity ID	Result
stores	N/A	N/A	Coupon applies to all products
stores	product	product ID	Coupon applies to the specific product with the provided ID
stores	collection	collection ID	Coupon applies to the specific collection with the provided ID

Namespace	Group	Entity ID	Result
bookings	N/A	N/A	Coupon applies to all services
bookings	service	service ID	Coupon applies to the specific service with the provided ID

Namespace	Group	Entity ID	Result
events	event	N/A	Coupon applies to all events
events	event	event ID	Coupon applies to the specific event with the provided ID
events	ticket	N/A	Coupon applies to all tickets
events	ticket	ticket ID	Coupon applies to the specific ticket with the provided ID

Namespace	Group	Entity ID	Result
pricingPlans	N/A	N/A	Coupon applies to all pricing plans
pricingPlans	plan	plan ID	Coupon applies to the specific pricing plan with the provided ID

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.

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 Code
  {
    "specification": {
      "name": "BuyXGetY",
      "code": "ABC",
      "active": true,
      "startTime": 1554066000000,
      "usageLimit": 10,
      "expirationTime": 1554325199999,
      "scope": {
        "namespace": "stores"
      },
      "limitedToOneItem": true,
      "buyXGetY": {
        "x": 3,
        "y": 2
      }
    }
  }

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

  Copy Code
  {
    "specification": {
      "name": "BuyXGetY",
      "code": "ABC",
      "active": true,
      "startTime": 1554066000000,
      "usageLimit": 10,
      "expirationTime": 1554325199999,
      "scope": {
        "namespace": "bookings",
        "group": {
          "name": "service",
          "entityId": "e599b709-1a8b-478a-ae80-26192944aef5"
        },
        "limitedToOneItem": true,
        "buyXGetY": {
          "x": 3,
          "y": 2
        }
      }
    }
  }

• If the coupon should apply to all tickets in Wix Events, your request can look like this:

  Copy Code
  {
    "specification": {
      "name": "BuyXGetY",
      "code": "ABC",
      "active": true,
      "startTime": 1554066000000,
      "usageLimit": 10,
      "expirationTime": 1554325199999,
      "scope": {
        "namespace": "events",
        "group": {
          "name": "ticket"
        }
      },
      "limitedToOneItem": true,
      "buyXGetY": {
        "x": 3,
        "y": 2
      }
    }
  }

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 Code
  {
    "specification": {
      "name": "Discount",
      "code": "ABC",
      "active": true,
      "startTime": 1554126066895,
      "usageLimit": 10,
      "scope": {
        "namespace": "stores",
        "group": {
          "name": "collection",
          "entityId": "e599b709-1a8b-478a-ae80-26192944aef5"
        }
      },
      "limitedToOneItem": false,
      "moneyOffAmount": 5
    }
  }

• If the coupon should apply to all services in Wix Bookings, your request can look like this:

  Copy Code
  {
    "specification": {
      "name": "Discount",
      "code": "ABC",
      "active": true,
      "startTime": 1554126066895,
      "scope": {
        "namespace": "bookings"
      },
      "limitedToOneItem": false,
      "moneyOffAmount": 5
    }
  }

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

  Copy Code
  {
    "specification": {
      "name": "Discount",
      "code": "ABC",
      "active": true,
      "startTime": 1554126066895,
      "scope": {
        "namespace": "events",
        "group": {
          "name": "ticket",
          "entityId": "e599b709-1a8b-478a-ae80-26192944aef5"
        }
      },
      "limitedToOneItem": false,
      "moneyOffAmount": 5
    }
  }

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 Code
{
  "specification": {
    "name": "SalePrice",
    "code": "ABC",
    "active": true,
    "startTime": 1554126541151,
    "scope": {
      "namespace": "stores",
      "group": {
        "name": "product",
        "entityId": "e599b709-1a8b-478a-ae80-26192944aef5"
      }
    },
    "limitedToOneItem": true,
    "fixedPriceAmount": 5
  }
}

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 Code
  {
    "specification": {
      "name": "111",
      "code": "ABC",
      "active": true,
      "startTime": 1554126716133,
      "scope": {
        "namespace": "stores",
        "group": {
          "name": "collection",
          "entityId": "e599b709-1a8b-478a-ae80-26192944aef5"
        }
      },
      "limitedToOneItem": true,
      "percentOffRate": 5
    }
  }

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

  Copy Code
  {
    "specification": {
      "name": "111",
      "code": "ABC",
      "active": true,
      "startTime": 1554126716133,
      "scope": {
        "namespace": "events",
        "group": {
          "name": "ticket"
        }
      },
      "limitedToOneItem": true,
      "percentOffRate": 5
    }
  }

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 Code
  {
    "specification": {
      "name": "FreeShipping",
      "code": "ABC",
      "active": true,
      "startTime": 1554126275300,
      "minimumSubtotal": 5,
      "limitedToOneItem": true,
      "freeShipping": true
    }
  }

• If the coupon should apply to all Wix Stores purchases with physical products that require shipping, your request can look like this:

  Copy Code
  {
    "specification": {
      "name": "FreeShipping",
      "code": "ABC",
      "active": true,
      "startTime": 1554126275300,
      "scope": {
        "namespace": "stores,"
      },
      "minimumSubtotal": 5,
      "limitedToOneItem": true,
      "freeShipping": true
    }
  }

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

Copy Code
{
  "specification": {
    "active": false
  },
  "fieldMask": {
    "paths": [
      "active"
    ]
  }
}

This use case describes deleting a coupon.

Copy Code
curl 'https://www.wixapis.com/stores/v2/coupons/<couponId>' \
   -X DELETE \
   -H 'Authorization: <AUTH>'

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