> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Wix Marketing Collections

## Article: Wix Marketing Collections

## Article Link: https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/wix-app-collections/wix-marketing-collections.md

## Article Content:

# Wix Marketing Collections

This article explains the fixed permissions and field structure for the Wix Marketing [Coupons](#coupons) collection.

> **Note:** This collection is a system collection, so you can't change its permissions in the CMS.

<blockquote class="tip">

**Tip:**
Before continuing, make sure you've read [Working with Wix App Collections](https://dev.wix.com/docs/develop-websites/articles/databases/wix-data/collections/working-with-wix-app-collections-and-code.md).

</blockquote>

## Coupons

This section explains the permissions and fields available in the Coupons collection.

To use the Coupons collection in code, refer to it as `Marketing/Coupons`.

::::tabs
:::REST_TAB
```
curl -X POST \
  'https://www.wixapis.com/wix-data/v2/items/query' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: <AUTH>' \
  -d '{
    "dataCollectionId": "Marketing/Coupons",
    "query": {}
  }'
```
:::
:::SDK_TAB
```js
import { items } from "@wix/data";

items.query("Marketing/Coupons")
  .find()
  .then((results) => {
    // handle the results
  });
```
:::
::::

### Permissions

The Coupons collection has the following [permissions](https://support.wix.com/en/article/cms-collection-permissions-overview):

- `read`: `ADMIN`
- `create`: None
- `update`: None
- `remove`: None

### Fields

This section describes each field in this collection and its properties.

> **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](https://support.wix.com/en/article/accessing-your-sites-dashboard).

Each field heading shows the field name followed by the field ID in parentheses, in the format "fieldName (`fieldId`)".

The fields are listed in the same order as the collection's default order in the CMS.

#### 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

**Sortable:** Yes

**Filter Support:** `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

**Sortable:** Yes

**Filter Support:** `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

**Sortable:** Yes

**Filter Support:** `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

**Sortable:** Yes

**Filter Support:** `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

**Sortable:** Yes

**Filter Support:** `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

**Sortable:** Yes

**Filter Support:** `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

**Sortable:** Yes

**Filter Support:** `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:**

**Sortable:** No

**Filter Support:** 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

**Sortable:** No

**Filter Support:** `eq`, `ne`

**Read-only:** Yes

> **Note:** The `limitedToOneItem` field only applies to coupons with `moneyOffAmount` or `percentOffRate` type.

#### Active (`active`)

**Description:** Indicates whether the coupon is currently [active](https://support.wix.com/en/article/managing-your-coupons).

**Type:** Boolean

**Can connect to data:** Yes

**Can use in dynamic page URL:** No

**Sortable:** No

**Filter Support:** `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

**Sortable:** Yes

**Filter Support:** `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

**Sortable:** No

**Filter Support:** No

**Read-only:** Yes

```json
{
  "namespace": "<namespace>",
  "group": {
    "name": "<groupName>",
    "entityId": "<entityId>"
  }
}
```

The following table lists the available options for the `namespace` and `group.name` fields:

|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.

```json
{ 
  "namespace": "stores"
}
```

**Example:** Scope for the coupon is defined as a specific product sold in your store.

```json
{ 
  "namespace": "stores",
  "group": {
    "name":"product",
    "entityId": "82921602-92d2-1787-08c8-207d12ef41d2" // ID of product
  } 
}
```

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.

```json
{ 
  "namespace": "events",
  "group": {
    "name":"ticket"
  }  
}
```

**Filtering with Scope**

You can filter using one of 3 scope fields:

- `scope.namespace`
- `scope.group.name`
- `scope.group.entityId`

**Filtering Example:** Query the Coupons collection for coupons within the Stores namespace.

::::tabs
:::REST_TAB
```
curl -X POST \
  'https://www.wixapis.com/wix-data/v2/items/query' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: <AUTH>' \
  -d '{
    "dataCollectionId": "Marketing/Coupons",
    "query": {
      "filter": {
        "scope.namespace": "stores"
      }
    }
  }'
```
:::
:::SDK_TAB
```js
import { items } from "@wix/data";

items.query("Marketing/Coupons")
  .eq("scope.namespace", "stores")
  .find();
```
:::
::::

**Filtering Example:** Query the Coupons collection for coupons applied to a specific product.

::::tabs
:::REST_TAB
```
curl -X POST \
  'https://www.wixapis.com/wix-data/v2/items/query' \
  -H 'Content-Type: application/json' \
  -H 'Authorization': <AUTH>' \
  -d '{
    "dataCollectionId": "Marketing/Coupons",
    "query": {
      "filter": {
        "scope.group.entityId": "82921602-92d2-1787-08c8-207d12ef41d2"
      }
    }
  }'
```
:::
:::SDK_TAB
```js
import { items } from "@wix/data";

items.query("Marketing/Coupons")
  .eq("scope.group.entityId", "82921602-92d2-1787-08c8-207d12ef41d2")
  .find();
```
:::
::::

#### 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

**Sortable:** No

**Filter Support:** `eq`, `ne`, `hasSome`

**Read-only:** Yes

> **Note:** The `type` field has one of the following values:
>
> - `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

**Sortable:** No

**Filter Support:** No

**Read-only:** Yes

```json
{ 
  "x": 3,
  "y": 1
}
```

#### Fixed Price Amount (`fixedPriceAmount`)

**Description:** A specific sale price.

**Type:** Number

**Can connect to data:** Yes

**Can use in dynamic page URL:** No

**Sortable:** No

**Filter Support:** 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

**Sortable:** No

**Filter Support:** 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

**Sortable:** No

**Filter Support:** 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

**Sortable:** No

**Filter Support:** 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

**Sortable:** Yes

**Filter Support:** `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

**Sortable:** Yes

**Filter Support:** `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

**Sortable:** No

**Filter Support:** `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

**Sortable:** No

**Filter Support:** Yes

**Read-only:** Yes

> **Note:** The `displayData` field is only relevant when the coupon is applied to a specific item. When the coupon is applied to all items in a group (for example, all products), `displayData` is empty. 

```json
"displayData": {
  "formattedPrice": "string",
  "mediaItem": "string",
  "name": "string"
}
```

#### 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

**Sortable:** Yes

**Filter Support:** Yes

**Read-only:** Yes