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>
List of coupon specifications to be created.
Deletes multiple coupons.
Permission Scopes
For app development, you must have one of the following permission scopes:function bulkDeleteCoupons(ids: Array<string>): Promise<BulkDeleteCouponsResponse>
IDs of coupons to delete.
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>
Coupon to create.
Deletes a coupon.
Permission Scopes
For app development, you must have one of the following permission scopes:function deleteCoupon(_id: string): Promise<void>
ID of the coupon to delete.
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>
ID of the coupon to retrieve.
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>
ID of the coupon to update.
Coupon information to update.