Migration Rest Portal

Build Apps

Go Headless

Client

API Preview

Develop Websites

REST

To use the Marketing API, install the `@wix/marketing` package using npm or Yarn:
  ```console
npm install @wix/marketing
```

or

```console
yarn add @wix/marketing
```

Then import `marketing` from `@wix/marketing`:

```js
import marketing from '@wix/marketing'
```
  

marketing

bulkCreateCoupons

bulkDeleteCoupons

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 the [introduction](#introduction) for a table of currently supported coupon scopes.

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

createCoupon

deleteCoupon

getCoupon

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

queryCoupons

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 the [introduction](#introduction) for a table of currently supported coupon scopes.

updateCoupon

To use the Coupons API, install the `@wix/marketing` package using npm or Yarn:
  ```console
npm install @wix/marketing
```

or

```console
yarn add @wix/marketing
```

Then import `{ coupons }` from `@wix/marketing`:

```js
import { coupons } from '@wix/marketing'
```
  

---
title: Introduction
---

# Introduction

The Coupons API allows you to create and manage coupons to promote loyalty and increase sales. Customers can then apply the coupon codes at checkout to take advantage of your offers. With the Coupons API, you can [create](#createcoupon) and [update](#updatecoupon) your coupons.  

## Terminology

- **Scope:** The coupon scope defines the items a coupon applies to. You can apply a coupon to all items in a specific Wix application, a group within the application, or a single item within a group.  

The following table lists the currently supported coupon scopes:
| namespace | group | entityId | Result |
|---|---|---|---|
| stores | -- | -- | Applies to all store products |
| stores | product | product ID | Applies to the specific store product with the provided ID |
| stores | collection | collection ID | Applies to the specific store collection with the provided ID |
| bookings | -- | -- | Applies to all bookings services |
| bookings | service | service ID | Applies to the specific bookings service with the provided ID |
| events | event | event ID | Applies to the specific event with the provided ID |
| events | ticket | -- | Applies to all event tickets |
| events | ticket | ticket ID | Applies to the specific event ticket with the provided ID |
| pricingPlans | -- | -- | Applies to all pricing plans |
| pricingPlans | plan | plan ID | Applies to the specific pricing plan with the provided ID |


# Coupons: Supported Filters and Sorting

The following table shows field support for filters and sorting
for the Coupon object:

| Field           | Supported Filters                             | Sortable |
| --------------- | --------------------------------------------- | -------- |
| `id`            | `$eq`,`$ne`,`$hasSome`,`$contains`,`$startsWith`   |     Sortable     |
| `dateCreated`   | `$eq`,`$ne`,`$hasSome`,`$lt`,`$lte`,`$gt`,`$gte`    | Sortable |
| `expired`       | `$eq`,`$ne` |          |
| `specification.active`  | `$eq`,`$ne`   |  |
| `specification.name` | `$eq`,`$ne`,`$hasSome`,`$contains`,`$startsWith` | Sortable |
| `specification.code` | `$eq`,`$ne`,`$hasSome`,`$contains`,`$startsWith`   |      Sortable    |
| `specification.usageLimit` | `$eq`,`$ne`,`$hasSome`,`$contains`,`$startsWith`  | Sortable |
| `specification.limitedToOneItem`   | `$eq`,`$ne`    |          |
| `scope.namespace` | `$eq`,`$ne`,`$hasSome`,`$contains`,`$startsWith`  | Sortable |
| `scope.group.name` | `$eq`,`$ne`,`$hasSome`,`$contains`,`$startsWith | Sortable` |
| `scope.group.entityId` | `$eq`,`$ne`,`$hasSome`,`$contains`,`$startsWith` |     Sortable     |


__Related content:__
[API Query Language](https://dev.wix.com/api/sdk/guides/filter-with-the-api-query-language),
[queryCoupons( )](https://dev.wix.com/api/sdk/marketing/coupons/querycoupons)


Coupons

ApplicationError

code

string

data

description

BulkActionMetadata

Number of items that couldn't be processed.

totalFailures

number

Number of items that were successfully processed.

totalSuccesses

Number of failures without details because detailed failure threshold was exceeded.

undetailedFailures

BulkCreateCouponResult

coupon

Coupon

itemMetadata

ItemMetadata

BulkCreateCouponsOptions

Whether to return full coupon entity in the response.

Default: `false`

returnFullEntity

boolean

BulkCreateCouponsResponse

bulkActionMetadata

results

BulkDeleteCouponsResponse

deleteMetadata

BuyXGetY

Number of purchased items required to receive free items.

Number of items received for free if required number of items were purchased.

ID of the app that created the coupon. Empty if created by the site owner.

appId

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

dateCreated

displayData

DisplayData

expired

How many times this coupon has been used.

numberOfUsages

specification

Specification

CreateCouponResponse

formattedPrice

mediaItem

MediaItem

name

Group

ID of the specific item in the group for which the coupon is applicable. If no `entityId` is specified, the coupon applies to all items in the group. In some cases when a group is specified, an `entityId` is required. See the [introduction](#introduction) for a list of currently supported entities for each namespace and group.

entityId

Name of coupon scope's group (e.g., product or collection in Wix Stores). See the [introduction](#introduction) for a table of currently supported coupon scopes.

Item ID. Should always be available, unless it's impossible (for example, when failing to create an item).

Details about the error in case of failure.

error

Index of the item within the request array. Allows for correlation between request and response items.

originalIndex

Whether the requested action was successful for this item. When `false`, the `error` field is populated.

success

height

width

Paging

limit

Offset since the beginning of the collection.

offset

Query

Filter string (e.g., when {"expired":"true"}, expired coupons will be returned).

filter

paging

sort

QueryCouponsResponse

coupons

totalResults

Scope

Group within a `namespace` for which the coupon is applicable. If no group is specified, the coupon applies to all items in the namespace. `group` is required in some cases. See the table in the [introduction](#introduction) for a list of currently supported groups for each namespace.

group

Scope namespace (Wix Stores, Wix Bookings, Wix Events, Wix Pricing Plans)

namespace

Receive free products when making a purchase.

For example, purchase `x` number of products and receive `y` number of products for free.

buyXGetY

fixedPriceAmount

Free shipping.

If `true`, the coupon applies to all items in all `namespaces`.

freeShipping

moneyOffAmount

percentOffRate

The coupon is only applicable when the order subtotal is over this amount.

minimumSubtotal

Specifies the type of line items this coupon will apply to. See the [introduction](#introduction) for a table of currently supported coupon scopes.

scope

Whether the coupon is currently [active](https://support.wix.com/en/article/wix-stores-activating-and-deactivating-coupons).

Default: `true`

active

Whether the coupon applies to subscription products.

If set to `true`, the discount will apply to all billing cycles.

appliesToSubscriptions

Coupon code. Must be unique for all coupons on your site.

Max: 20 characters

discountedCycleCount

expirationTime

Maximum number of times the coupon can be used per customer.

limitPerCustomer

Whether the coupon is limited to one item.

If `true` and a customer pays for multiple items, the discount applies to only the lowest priced item.
Coupons with a `bookings` `scope.namespace` are always limited to one item.

limitedToOneItem

startTime

type

Maximum number of times the coupon can be used.

>**Note:** Multiple purchases by the same customer or purchases by different customers are both counted toward `usageLimit`.

Setup