"Coupons" Collection Fields
To use the Coupons collection in code, refer to it as "Marketing/Coupons"
.
1
This document describes the permissions and fields in your Coupons collection.
Permissions
The Coupons collection has the following permissions:
- Read: Admin
- Create: None
- Update: None
- Delete: None
You cannot change the Coupons collection's permissions.
Fields
Note: This app collection contains read-only fields that cannot be managed from the collection. You can update the fields from the relevant app in your site’s dashboard.
The field name is listed as the heading of each section, with the field ID listed in parentheses, like this: Name (name). The fields appear in this document in the order in which they appear in your collection by default.
ID (_id)
Description: The ID of the coupon. This is a system field and is hidden by default.
Type: Text
Can connect to data: Yes
Can use in dynamic page URL: Yes
Can be sorted: Yes
Can be filtered: eq, ne, hasSome, contains, startsWith
Read-only: Yes
Name (name)
Description: Name of the coupon.
Type: Text
Can connect to data: Yes
Can use in dynamic page URL: No
Can be sorted: Yes
Can be filtered: eq, ne, hasSome, contains, startsWith
Read-only: Yes
Code (code)
Description: Coupon code.
Type: Text
Can connect to data: Yes
Can use in dynamic page URL: No
Can be sorted: Yes
Can be filtered: eq, ne, hasSome, contains, startsWith
Read-only: Yes
Start Time (startTime)
Description: Start date and time of the coupon.
Type: Date and Time
Can connect to data: Yes
Can use in dynamic page URL: No
Can be sorted: Yes
Can be filtered: eq, ne, hasSome, lt, lte, gt, gte
Read-only: Yes
Expiration Time (expirationTime)
Description: End date and time of the coupon.
Type: Date and Time
Can connect to data: Yes
Can use in dynamic page URL: No
Can be sorted: Yes
Can be filtered: eq, ne, hasSome, lt, lte, gt, gte
Read-only: Yes
Usage Limit (usageLimit)
Description: Maximum number of times a coupon can be used.
Type: Number
Can connect to data: Yes
Can use in dynamic page URL: No
Can be sorted: Yes
Can be filtered: eq, ne, hasSome, lt, lte, gt, gte
Read-only: Yes
Limit Per Customer (limitPerCustomer)
Description: Maximum number of times the coupon can be used per customer.
Type: Number
Can connect to data: Yes
Can use in dynamic page URL: No
Can be sorted: Yes
Can be filtered: eq, ne, hasSome, lt, lte, gt, gte
Read-only: Yes
Applies to Subscriptions (appliesToSubscriptions)
Description:
Type: Boolean
Can connect to data: Yes
Can use in dynamic page URL:
Can be sorted: No
Can be filtered: Yes
Read-only: Yes
Limited To One Item (limitedToOneItem)
Description: Indicates whether the coupon is limited to 1 discount per order. If true and a customer buys multiple items that the coupon applies to, only the lowest priced item is discounted.
Type: Boolean
Can connect to data:
Can use in dynamic page URL: No
Can be sorted: No
Can be filtered: eq, ne
Read-only: Yes
Note: This field only applies to coupons with Type "moneyOffAmount" or "percentOffRate".
Active (active)
Description: Indicates whether the coupon is currently active.
Type: Boolean
Can connect to data: Yes
Can use in dynamic page URL: No
Can be sorted: No
Can be filtered: eq, ne
Read-only: Yes
Minimum Subtotal (minimumSubtotal)
Description: The coupon can be used when the order subtotal is over this amount.
Type: Number
Can connect to data: Yes
Can use in dynamic page URL: No
Can be sorted: Yes
Can be filtered: eq, ne, hasSome, lt, lte, gt, gte
Read-only: Yes
Scope (scope)
Description: Scope for the coupon as defined in a JSON object.
Type: JSON
Can connect to data: No
Can use in dynamic page URL: No
Can be sorted: No
Can be filtered: No
Read-only: Yes
1
The following table lists the available options for Namespace and Group:
Namespace | Group |
---|---|
stores | product |
collection | |
bookings | service |
events | event |
ticket |
You can define the scope for a coupon as an entire namespace, a group within a namespace, or an item within a group. See the examples below.
Example: Scope for the coupon is defined as all products sold in your store.
1
Example: Scope for the coupon is defined as a specific product sold in your store.
1
Since the events namespace has both ticket and event groups, and you can't apply a single coupon to all tickets and events at the same time, you can't define the scope as just the namespace events. For events you need to define the scope as a group or a specific item in a group.
Example: Scope for the coupon is defined as all tickets for events.
1
Filtering with Scope
You can filter using one of 3 scopes:
- "scope.namespace"
- "scope.group.name"
- "scope.group.entity"
Filtering Example: Query the Coupons collection for coupons within the Stores namespace.
1
Filtering Example: Query the Coupons collection for coupons applied to a specific product.
1
Type (type)
Description: The type of coupon (see note for available options).
Type: Text
Can connect to data: Yes
Can use in dynamic page URL: No
Can be sorted: No
Can be filtered: eq, ne, hasSome
Read-only: Yes
Note: The "type" value is one of the following:
- "BuyXGetY" - Free products when making a purchase
- "FixedPrice" - Specific sale price
- "FreeShipping" - Free shipping
- "MoneyOff" - Fixed price discount
- "PercentOff" - Discount as a percentage
Buy X Get Y (buyXGetY)
Description: A JSON object representing X and Y in the following scenario: if a visitor purchases X number of products, they receive Y number of products for free.
Type: JSON
Can connect to data: No
Can use in dynamic page URL: No
Can be sorted: No
Can be filtered: No
Read-only: Yes
1
Fixed Price Amount (fixedPriceAmount)
Description: A specific sale price.
Type: Number
Can connect to data: Yes
Can use in dynamic page URL: No
Can be sorted: No
Can be filtered: No
Read-only: Yes
Free Shipping (freeShipping)
Description: Indicates whether shipping is free.
Type: Boolean
Can connect to data: Yes
Can use in dynamic page URL: No
Can be sorted: No
Can be filtered: No
Read-only: Yes
Money Off Amount (moneyOffAmount)
Description: A fixed amount subtracted from the original price.
Type: Number
Can connect to data: Yes
Can use in dynamic page URL: No
Can be sorted: No
Can be filtered: No
Read-only: Yes
Percent Off Rate (percentOffRate)
Description: A percentage subtracted from the original price.
Type: Number
Can connect to data: Yes
Can use in dynamic page URL: No
Can be sorted: No
Can be filtered: No
Read-only: Yes
Date Created (_dateCreated)
Description: The date the coupon was created.
Type: Date and Time
Can connect to data: Yes
Can use in dynamic page URL: No
Can be sorted: Yes
Can be filtered: eq, ne, hasSome, lt, lte, gt, gte
Read-only: Yes
Number of Usages (numberOfUsages)
Description: The total number of times a coupon was used by all customers.
Type: Number
Can connect to data: Yes
Can use in dynamic page URL: No
Can be sorted: Yes
Can be filtered: eq, ne, hasSome, lt, lte, gt, gte
Read-only: Yes
Expired (expired)
Description: Indicates whether the expiration time passed and the coupon is expired.
Type: Boolean
Can connect to data: Yes
Can use in dynamic page URL: No
Can be sorted: No
Can be filtered: eq, ne
Read-only: Yes
Display Data (displayData)
Description: Display information for the item the coupon is applicable for defined as a JSON object (e.g. a Stores product or a Bookings service).
Type: JSON
Can connect to data: No
Can use in dynamic page URL: No
Can be sorted: No
Can be filtered: Yes
Read-only: Yes
Note: This field is only relevant when the coupon is applied to a specific item. When the coupon is applied to all items in a group (e.g. all products), Display Data is empty.
1
App ID (appId)
Description: The ID of the 3rd-party app that created the coupon. Empty if created by the site owner.
Type: Text
Can connect to data: No
Can use in dynamic page URL: No
Can be sorted: Yes
Can be filtered: Yes
Read-only: Yes
Related APIs
Use the following APIs to work with data from the Coupons collection: