CorvidReference

coupons

The Coupons API is used to manage your site's coupons.

You can offer your customers discount coupons to promote loyalty and increase sales. Customers can then apply the coupon codes at checkout to take advantage of your offers. You can apply coupons to items in Wix Stores, Wix Bookings, and Wix Events.

To use the Coupons API, import wixMarketing from the wix-marketing-backend module:

   import wixMarketing from 'wix-marketing-backend';

Table of Contents

OBJECTS

?
Objects used when setting, getting, or calling the properties and methods listed above.
CouponInfoAn object representing information for creating or updating a coupon.
CouponScopeAn object containing the scope of a coupon.
CouponTypeBuyXGetYAn object defining the number of purchases required and the number of free items received for a "Buy X Get Y" coupon type.
ScopeGroup

An object specifying the group within a CouponScope namespace for which the coupon is applicable.

createCoupon( )

Creates a new coupon.

Description

The createCoupon() function returns a Promise that resolves to the ID of the the newly created coupon after it has been successfully created.

When creating a coupon, the specified CouponInfo object must contain a value for exactly 1 of the following coupon properties. This defines the coupon type.

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

    When creating a new coupon, the specified CouponInfo 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.

Syntax

function createCoupon(couponInfo: CouponInfo): Promise<string>
PARAMETERS
?
Values that you pass to a function.
couponInfo
The information to use when creating the coupon.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<string>
Fulfilled - ID of the newly created coupon.

Examples

Create a new coupon with options

import wixMarketing from 'wix-marketing-backend';

export function createCoupon() {
  let couponData = {
    "name": "My Coupon",
    "code": "myCouponCode",
    "startTime": new Date(),
    "expirationTime": new Date(2020,12,31),
    "usageLimit": 100,
    "limitedToOneItem": true,
    "active": true,
    "scope": {
      "namespace": "stores"
    },
    "moneyOffAmount": 10
  };

  return wixMarketing.coupons.createCoupon(couponData);
}

// Returns promise that resolves to:
// bff1f257-5e7e-437d-9f86-098de337cae6

Create a new "money off" coupon

import wixMarketing from 'wix-marketing-backend';

export function createCoupon() {
  let couponData = {
    "name": "My Coupon",
    "code": "myCouponCode",
    "startTime": new Date(),
    "scope": {
      "namespace": "stores"
    },
    "moneyOffAmount": 10 // $10 off original price
  };

  return wixMarketing.coupons.createCoupon(couponData);
}

// Returns promise that resolves to:
// bff1f257-5e7e-437d-9f86-098de337cae6

Create a new free shipping coupon

import wixMarketing from 'wix-marketing-backend';

export function createCoupon() {
  let couponData = {
    "name": "My Coupon",
    "code": "myCouponCode",
    "startTime": new Date(),
    "freeShipping": true
  };

  return wixMarketing.coupons.createCoupon(couponData);
}

// Returns promise that resolves to:
// bff1f257-5e7e-437d-9f86-098de337cae6

Create a new "buy x, get y" coupon

import wixMarketing from 'wix-marketing-backend';

export function createCoupon() {
  let couponData = {
    "name": "My Coupon",
    "code": "myCouponCode",
    "startTime": new Date(),
    "scope": {
      "namespace": "stores"
    },
    "buyXGetY": { // Buy 2 items, get 1 free
      "x": 2,
      "y": 1
    }
  };

  return wixMarketing.coupons.createCoupon(couponData);
}

// Returns promise that resolves to:
// bff1f257-5e7e-437d-9f86-098de337cae6

Create a new coupon that applies to a specific store product

import wixMarketing from 'wix-marketing-backend';

export function createCoupon() {
  let couponData = {
    "name": "My Coupon",
    "code": "myCouponCode",
    "startTime": new Date(),
    "scope": { // Coupon applies to the store product with the specified ID
      "namespace": "stores",
      "group": {
        "name": "product",
        "entityId": "3db41c71-6cb6-45f5-88fc-aaf05ed22e54"
      }
    },
    "moneyOffAmount": 10
  };

  return wixMarketing.coupons.createCoupon(couponData);
}

// Returns promise that resolves to:
// bff1f257-5e7e-437d-9f86-098de337cae6

Create a new coupon that applies to all event tickets

import wixMarketing from 'wix-marketing-backend';

export function createCoupon() {
  let couponData = {
    "name": "My Coupon",
    "code": "myCouponCode",
    "startTime": new Date(),
    "scope": { // Coupon applies to all event tickets
      "namespace": "events",
      "group": {
        "name": "ticket"
      }
    },
    "moneyOffAmount": 5 // $5 off original ticket price
  };

  return wixMarketing.coupons.createCoupon(couponData);
}

// Returns promise that resolves to:
// bff1f257-5e7e-437d-9f86-098de337cae6

deleteCoupon( )

Deletes an existing coupon.

Description

The deleteCoupon() function returns a Promise that resolves when the coupon is successfully deleted.

Syntax

function deleteCoupon(couponId: string): Promise<void>
PARAMETERS
?
Values that you pass to a function.
couponId
string
ID of the coupon to delete.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<void>
Fulfilled - When the coupon is deleted.

Examples

Delete a coupon

import wixMarketing from 'wix-marketing-backend';

export function deleteCoupon(couponId) {
  return wixMarketing.coupons.deleteCoupon(couponId);
}

// Returns a promise that is resolved when
// the coupon is deleted.

updateCouponFields( )

Updates the specified fields of an existing coupon.

Description

The updateCoupon() function returns a Promise that resolves when the coupon is successfully updated.

Only the properties passed in the CouponInfo 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.

Syntax

function updateCouponFields(couponId: string, couponInfo: CouponInfo): Promise<void>
PARAMETERS
?
Values that you pass to a function.
couponId
string
ID of the coupon to update.
couponInfo
The information to update the coupon with.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<void>
Fulfilled - When the coupon is updated.

Examples

Update an existing coupon

import wixMarketing from 'wix-marketing-backend';

export function updateCouponFields(couponId, couponData) {
  return wixMarketing.coupons.updateCouponFields(couponId, couponData);
}

// Returns a promise that is resolved when
// the coupon is updated.

Update a coupon's expiration date

import wixMarketing from 'wix-marketing-backend';

export function updateCouponFields() {
  let couponId = "bff1f257-5e7e-437d-9f86-098de337cae6";

  let newExpirationDate = new Date();
  newExpirationDate.setMonth(newExpirationDate.getMonth() + 1);

  let couponData = {
    "expirationTime": newExpirationDate // Coupon ends in 1 month
  };

  return wixMarketing.coupons.updateCouponFields(couponId, couponData);
}

// Returns a promise that is resolved when
// the coupon is updated.

CouponInfo

An object representing information for creating or updating a coupon.

Description

When creating a coupon, you must pass exactly 1 of the following coupon properties with a value. This defines the coupon type.

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

    When updating an existing coupon, you cannot change the coupon type.

    When creating a coupon, you must provide a value for either minimumSubtotal or scope in your coupon information. The exception is for a freeShipping coupon type, for which you cannot apply a scope and minimumSubtotal is optional.

See Also

createCoupon()

Syntax

type CouponInfo = {
  name: string
  code: string
  startTime: Date
  expirationTime: Date
  usageLimit: number
  limitedToOneItem: boolean
  active: boolean
  minimumSubtotal: number
  scope: CouponScope
  buyXGetY: CouponTypeBuyXGetY
  freeShipping: boolean
  moneyOffAmount: number
  percentOffRate: number
  fixedPriceAmount: number
}
MEMBERS
?
The properties of an object.
name
string
Name of coupon.
code
string
Coupon code. Must be unique for all coupons in your site. Maximum 20 characters.
startTime
Date
Start date and time of coupon.
expirationTime(Optional)
Date
End date and time of coupon.
usageLimit(Optional)
number
The maximum number of times a coupon can be used. Note that multiple purchases by the same customer or purchases by different customers are both counted toward usage limit.
limitedToOneItem(Optional)
boolean
Indicates whether the coupon is limited to 1 discount per order. If true and a customer pays for multiple items the coupon applies to, only the lowest priced item is discounted. Coupons with a bookings namespace are always limited to one item.
active(Optional)
boolean
Indicates whether the coupon is currently active.
minimumSubtotal(Optional)
number
The coupon is only applicable when the order subtotal is over this amount.
scope(Optional)
Scope of the coupon. When no scope is defined, the coupon applies to all items in all namespaces in the site.
buyXGetY(Optional)
Coupon type: Free products when making a purchase. Currently only supported for coupons with a stores namespace.
freeShipping(Optional)
boolean
Coupon type: Free shipping. If true, the coupon applies to all items in all namespaces in the site.
moneyOffAmount(Optional)
number
Coupon type: Fixed price discount.
percentOffRate(Optional)
number
Coupon type: Discount as a percentage.
fixedPriceAmount(Optional)
number
Coupon type: Specific sale price. Currently only supported for coupons with a stores namespace.

Examples

Create a new coupon with options

import wixMarketing from 'wix-marketing-backend';

export function createCoupon() {
  let couponData = {
    "name": "My Coupon",
    "code": "myCouponCode",
    "startTime": new Date(),
    "expirationTime": new Date(2020,12,31),
    "usageLimit": 100,
    "limitedToOneItem": true,
    "active": true,
    "scope": {
      "namespace": "stores"
    },
    "moneyOffAmount": 10
  };

  return wixMarketing.coupons.createCoupon(couponData);
}

// Returns promise that resolves to:
// bff1f257-5e7e-437d-9f86-098de337cae6

Create a new "money off" coupon

import wixMarketing from 'wix-marketing-backend';

export function createCoupon() {
  let couponData = {
    "name": "My Coupon",
    "code": "myCouponCode",
    "startTime": new Date(),
    "scope": {
      "namespace": "stores"
    },
    "moneyOffAmount": 10 // $10 off original price
  };

  return wixMarketing.coupons.createCoupon(couponData);
}

// Returns promise that resolves to:
// bff1f257-5e7e-437d-9f86-098de337cae6

Create a new "buy x, get y" coupon

import wixMarketing from 'wix-marketing-backend';

export function createCoupon() {
  let couponData = {
    "name": "My Coupon",
    "code": "myCouponCode",
    "startTime": new Date(),
    "scope": {
      "namespace": "stores"
    },
    "buyXGetY": { // Buy 2 items, get 1 free
      "x": 2,
      "y": 1
    }
  };

  return wixMarketing.coupons.createCoupon(couponData);
}

// Returns promise that resolves to:
// bff1f257-5e7e-437d-9f86-098de337cae6

Create a new coupon that applies to a specific store product

import wixMarketing from 'wix-marketing-backend';

export function createCoupon() {
  let couponData = {
    "name": "My Coupon",
    "code": "myCouponCode",
    "startTime": new Date(),
    "scope": { // Coupon applies to the store product with the specified ID
      "namespace": "stores",
      "group": {
        "name": "product",
        "entityId": "3db41c71-6cb6-45f5-88fc-aaf05ed22e54"
      }
    },
    "moneyOffAmount": 10
  };

  return wixMarketing.coupons.createCoupon(couponData);
}

// Returns promise that resolves to:
// bff1f257-5e7e-437d-9f86-098de337cae6

Update a coupon's expiration date

import wixMarketing from 'wix-marketing-backend';

export function updateCouponFields() {
  let couponId = "bff1f257-5e7e-437d-9f86-098de337cae6";

  let newExpirationDate = new Date();
  newExpirationDate.setMonth(newExpirationDate.getMonth() + 1);

  let couponData = {
    "expirationTime": newExpirationDate // Coupon ends in 1 month
  };

  return wixMarketing.coupons.updateCouponFields(couponId, couponData);
}

// Returns a promise that is resolved when
// the coupon is updated.

CouponScope

An object containing the scope of a coupon.

Description

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:

namespacegroupentityIdResult
stores----Applies to all store products
storesproductproduct IDApplies to the specific store product with the provided ID
storescollectioncollection IDApplies to the specific store collection with the provided ID
bookings----Applies to all bookings services
bookingsserviceservice IDApplies to the specific bookings service with the provided ID
eventseventevent IDApplies to the specific event with the provided ID
eventsticket--Applies to all event tickets
eventsticketticket IDApplies to the specific event ticket with the provided ID

Syntax

type CouponScope = {
  namespace: string
  group: ScopeGroup
}
MEMBERS
?
The properties of an object.
namespace
string

Wix application for which the coupon is applicable. One of the following:

  • "stores"
  • "bookings"
  • "events"
group(Optional)
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.

Examples

Create a new coupon that applies to a specific store product

import wixMarketing from 'wix-marketing-backend';

export function createCoupon() {
  let couponData = {
    "name": "My Coupon",
    "code": "myCouponCode",
    "startTime": new Date(),
    "scope": { // Coupon applies to the store product with the specified ID
      "namespace": "stores",
      "group": {
        "name": "product",
        "entityId": "3db41c71-6cb6-45f5-88fc-aaf05ed22e54"
      }
    },
    "moneyOffAmount": 10
  };

  return wixMarketing.coupons.createCoupon(couponData);
}

// Returns promise that resolves to:
// bff1f257-5e7e-437d-9f86-098de337cae6

Create a new coupon that applies to all bookings services

import wixMarketing from 'wix-marketing-backend';

export function createCoupon() {
  let couponData = {
    "name": "My Coupon",
    "code": "myCouponCode",
    "startTime": new Date(),
    "scope": {
      "namespace": "bookings" // Coupon applies to all booking services
    },
    "moneyOffAmount": 10
  };

  return wixMarketing.coupons.createCoupon(couponData);
}

// Returns promise that resolves to:
// bff1f257-5e7e-437d-9f86-098de337cae6

Create a new coupon that applies to all event tickets

import wixMarketing from 'wix-marketing-backend';

export function createCoupon() {
  let couponData = {
    "name": "My Coupon",
    "code": "myCouponCode",
    "startTime": new Date(),
    "scope": { // Coupon applies to all event tickets
      "namespace": "events",
      "group": {
        "name": "ticket"
      }
    },
    "moneyOffAmount": 5 // $5 off original ticket price
  };

  return wixMarketing.coupons.createCoupon(couponData);
}

// Returns promise that resolves to:
// bff1f257-5e7e-437d-9f86-098de337cae6

CouponTypeBuyXGetY

An object defining the number of purchases required and the number of free items received for a "Buy X Get Y" coupon type.

Description

An object that specifies x and y in the following scenario: if a visitor purchases x number of products, they receive y number of products for free.

Syntax

type CouponTypeBuyXGetY = {
  x: number
  y: number
}
MEMBERS
?
The properties of an object.
x
number
Number of purchased items required to receive free items.
y
number
Number of items received for free if required number of items were purchased.

Examples

Create a new "buy x, get y" coupon

import wixMarketing from 'wix-marketing-backend';

export function createCoupon() {
  let couponData = {
    "name": "My Coupon",
    "code": "myCouponCode",
    "startTime": new Date(),
    "scope": {
      "namespace": "stores"
    },
    "buyXGetY": { // Buy 2 items, get 1 free
      "x": 2,
      "y": 1
    }
  };

  return wixMarketing.coupons.createCoupon(couponData);
}

// Returns promise that resolves to:
// bff1f257-5e7e-437d-9f86-098de337cae6

ScopeGroup

An object specifying the group within a CouponScope namespace for which the coupon is applicable.

Syntax

type ScopeGroup = {
  name: string
  entityId: string
}
MEMBERS
?
The properties of an object.
name
string
Name of the group.
entityId(Optional)
string
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.

Examples

Create a new coupon that applies to a specific store product

import wixMarketing from 'wix-marketing-backend';

export function createCoupon() {
  let couponData = {
    "name": "My Coupon",
    "code": "myCouponCode",
    "startTime": new Date(),
    "scope": { // Coupon applies to the store product with the specified ID
      "namespace": "stores",
      "group": {
        "name": "product",
        "entityId": "3db41c71-6cb6-45f5-88fc-aaf05ed22e54"
      }
    },
    "moneyOffAmount": 10
  };

  return wixMarketing.coupons.createCoupon(couponData);
}

// Returns promise that resolves to:
// bff1f257-5e7e-437d-9f86-098de337cae6

Create a new coupon that applies to all bookings services

import wixMarketing from 'wix-marketing-backend';

export function createCoupon() {
  let couponData = {
    "name": "My Coupon",
    "code": "myCouponCode",
    "startTime": new Date(),
    "scope": {
      "namespace": "bookings" // Coupon applies to all booking services
    },
    "moneyOffAmount": 10
  };

  return wixMarketing.coupons.createCoupon(couponData);
}

// Returns promise that resolves to:
// bff1f257-5e7e-437d-9f86-098de337cae6

Create a new coupon that applies to all event tickets

import wixMarketing from 'wix-marketing-backend';

export function createCoupon() {
  let couponData = {
    "name": "My Coupon",
    "code": "myCouponCode",
    "startTime": new Date(),
    "scope": { // Coupon applies to all event tickets
      "namespace": "events",
      "group": {
        "name": "ticket"
      }
    },
    "moneyOffAmount": 5 // $5 off original ticket price
  };

  return wixMarketing.coupons.createCoupon(couponData);
}

// Returns promise that resolves to:
// bff1f257-5e7e-437d-9f86-098de337cae6