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 and update 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 |
Setup
To use the Coupons API, install the @wix/marketing package using npm or Yarn:
1npm install @wix/marketing
or
1yarn add @wix/marketing
Then import { coupons } from @wix/marketing:
1import { coupons } from '@wix/marketing'
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, queryCoupons( )
Creates multiple coupons.
Permission Scopes
For app development, you must have one of the following permission scopes:function bulkCreateCoupons(specifications: Array<Specification>, options: BulkCreateCouponsOptions): Promise<BulkCreateCouponsResponse>
Deletes multiple coupons.
Permission Scopes
For app development, you must have one of the following permission scopes:function bulkDeleteCoupons(ids: Array<string>): Promise<BulkDeleteCouponsResponse>
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 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"
Permission Scopes
For app development, you must have one of the following permission scopes:function createCoupon(specification: Specification): Promise<CreateCouponResponse>
Deletes a coupon.
Permission Scopes
For app development, you must have one of the following permission scopes:function deleteCoupon(_id: string): Promise<void>
Retrieves a coupon by ID.
Permission Scopes
For app development, you must have one of the following permission scopes:function getCoupon(_id: string): Promise<Coupon>
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:function queryCoupons(query: Query): Promise<QueryCouponsResponse>
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 for a table of currently supported coupon scopes.
Permission Scopes
For app development, you must have one of the following permission scopes:function updateCoupon(_id: string, specification: Specification): Promise<void>