# The buy x pay y promotion object

A buy x pay y promotion object is returned as part of the response body of each successful list, retrieve, create or update API call to the `/api/buy_x_pay_y_promotions` endpoint.

## Fields

| Field                                            | Type       | Description                                                                                                                                                                                         |
| ------------------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **type**                                         | `string`   | `buy_x_pay_y_promotions`                                                                                                                                                                            |
| **id**                                           | `string`   | The buy x pay y promotion unique identifier                                                                                                                                                         |
| links.**self**                                   | `string`   | The buy x pay y promotion endpoint URL                                                                                                                                                              |
| attributes.**name**                              | `string`   | The promotion's internal name.                                                                                                                                                                      |
| attributes.**currency\_code**                    | `string`   | The international 3-letter currency code as defined by the ISO 4217 standard.                                                                                                                       |
| attributes.**exclusive**                         | `boolean`  | Indicates if the promotion will be applied exclusively, based on its priority score.                                                                                                                |
| attributes.**priority**                          | `integer`  | The priority assigned to the promotion (lower means higher priority).                                                                                                                               |
| attributes.**starts\_at**                        | `datetime` | The activation date/time of this promotion.                                                                                                                                                         |
| attributes.**expires\_at**                       | `datetime` | The expiration date/time of this promotion (must be after starts\_at).                                                                                                                              |
| attributes.**total\_usage\_limit**               | `integer`  | The total number of times this promotion can be applied. When 'null' it means promotion can be applied infinite times.                                                                              |
| attributes.**total\_usage\_count**               | `integer`  | The number of times this promotion has been applied.                                                                                                                                                |
| attributes.**total\_usage\_reached**             | `boolean`  | Indicates if the promotion has been applied the total number of allowed times.                                                                                                                      |
| attributes.**active**                            | `boolean`  | Indicates if the promotion is active (enabled and not expired).                                                                                                                                     |
| attributes.**status**                            | `string`   | The promotion status. One of 'disabled', 'expired', 'pending', 'active', or 'inactive'.                                                                                                             |
| attributes.**weight**                            | `integer`  | The weight of the promotion, computed by exclusivity, priority, type and start time. Determines the order of application, higher weight apply first.                                                |
| attributes.**coupons\_count**                    | `integer`  | The total number of coupons created for this promotion.                                                                                                                                             |
| attributes.**\_disable**                         | `boolean`  | Send this attribute if you want to mark this resource as disabled.                                                                                                                                  |
| attributes.**\_enable**                          | `boolean`  | Send this attribute if you want to mark this resource as enabled.                                                                                                                                   |
| attributes.**disabled\_at**                      | `datetime` | Time at which this resource was disabled.                                                                                                                                                           |
| attributes.**\_add\_tags**                       | `string`   | Comma separated list of tags to be added. Duplicates, invalid and non existing ones are discarded. Cannot be passed by sales channels.                                                              |
| attributes.**\_remove\_tags**                    | `string`   | Comma separated list of tags to be removed. Duplicates, invalid and non existing ones are discarded. Cannot be passed by sales channels.                                                            |
| attributes.**created\_at**                       | `datetime` | Time at which the resource was created.                                                                                                                                                             |
| attributes.**updated\_at**                       | `datetime` | Time at which the resource was last updated.                                                                                                                                                        |
| attributes.**reference**                         | `string`   | A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever. |
| attributes.**reference\_origin**                 | `string`   | Any identifier of the third party system that defines the reference code.                                                                                                                           |
| attributes.**metadata**                          | `object`   | Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.                                        |
| attributes.**x**                                 | `integer`  | The quantity which defines the threshold for free items (works by multiple of x).                                                                                                                   |
| attributes.**y**                                 | `integer`  | The quantity which defines how many items you get for free, with the formula x-y.                                                                                                                   |
| attributes.**cheapest\_free**                    | `boolean`  | Indicates if the cheapest items are discounted, allowing all of the SKUs in the associated list to be eligible for counting.                                                                        |
| relationships.**market**                         | `object`   | The associated market.                                                                                                                                                                              |
| relationships.**promotion\_rules**               | `array`    | The associated promotion rules.                                                                                                                                                                     |
| relationships.**order\_amount\_promotion\_rule** | `object`   | The associated order amount promotion rule.                                                                                                                                                         |
| relationships.**sku\_list\_promotion\_rule**     | `object`   | The associated SKU list promotion rule.                                                                                                                                                             |
| relationships.**coupon\_codes\_promotion\_rule** | `object`   | The associated coupon codes promotion rule.                                                                                                                                                         |
| relationships.**custom\_promotion\_rule**        | `object`   | The associated custom promotion rule.                                                                                                                                                               |
| relationships.**sku\_list**                      | `object`   | The associated SKU list.                                                                                                                                                                            |
| relationships.**coupons**                        | `array`    | The associated coupons through coupon codes promotion rule.                                                                                                                                         |
| relationships.**attachments**                    | `array`    | The associated attachments.                                                                                                                                                                         |
| relationships.**events**                         | `array`    | The associated events.                                                                                                                                                                              |
| relationships.**tags**                           | `array`    | The associated tags. Cannot be passed by sales channels.                                                                                                                                            |
| relationships.**versions**                       | `array`    | The associated changes.                                                                                                                                                                             |
| relationships.**event\_stores**                  | `array`    | The associated event stores.                                                                                                                                                                        |
| relationships.**skus**                           | `array`    | The associated SKUs.                                                                                                                                                                                |
| meta.**mode**                                    | `string`   | The resource environment (can be one of `test` or `live`)                                                                                                                                           |