POST
/
api-offers
/
promo
/
create
curl --request POST \
  --url https://live.copilot.fabric.inc/api-offers/promo/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-site-context: <x-site-context>' \
  --data '{
  "title": "CREATE PROMO",
  "buyOperator": "OR",
  "promo": [
    {
      "discount": [
        {
          "unit": "%OFF",
          "value": 10,
          "discountId": 1,
          "autoAdd": false,
          "ON": {
            "kind": "SKU",
            "value": "*",
            "quantity": 2,
            "includeOperator": "OR",
            "excludeOperator": "AND"
          },
          "set": [
            "A"
          ]
        }
      ],
      "targetProducts": [
        {
          "kind": "SKU",
          "value": "*",
          "operator": "IN",
          "discountId": 1
        }
      ],
      "condition": [
        {
          "operator": "AND",
          "includeOperator": "OR",
          "excludeOperator": "AND",
          "conditions": [
            {
              "key": "SKU",
              "value": "*",
              "operator": "IN"
            }
          ],
          "set": "A"
        }
      ]
    }
  ],
  "startDate": "2019-08-24T14:15:22Z",
  "endDate": "2019-08-25T14:15:22Z",
  "isExclusive": true,
  "type": "PRODUCT",
  "stackingType": "STACKABLE",
  "level": 1,
  "termsAndConditions": [
    {
      "title": "Terms Applied",
      "description": "Items cannot be exchanged"
    }
  ],
  "promotionMessages": [
    {
      "title": "Buy 1 get 1 free",
      "message": "Offer valid at participating stores through September 5, 2023.",
      "pages": [
        "PDP",
        "Cart"
      ],
      "locales": [
        "en-CA",
        "fr-CA"
      ]
    }
  ],
  "proximityMessages": [
    {
      "threshold": 1,
      "localizedMessages": [
        {
          "locales": [
            "<string>"
          ],
          "message": "<string>"
        }
      ]
    }
  ],
  "shipmentMethodIds": [
    1000001
  ],
  "eligiblePriceList": [
    10000056
  ],
  "limits": [
    {
      "kind": "ORDER",
      "value": 2
    }
  ],
  "note": "Independence day sale!",
  "additionalAttributes": [
    {
      "key": "type",
      "value": "Birthday",
      "attributeId": 100000
    }
  ]
}'
{
  "_id": "abcdefg1ee7ce20123456789",
  "promoId": 100013,
  "promoCodes": [
    "SUMMER100",
    "SUMMER20"
  ],
  "state": "SCHEDULED",
  "isImplicit": true,
  "title": "CREATE PROMO",
  "buyOperator": "OR",
  "promo": [
    {
      "discount": [
        {
          "unit": "%OFF",
          "value": 10,
          "discountId": 1,
          "autoAdd": false,
          "ON": {
            "kind": "SKU",
            "value": "*",
            "quantity": 2,
            "includeOperator": "OR",
            "excludeOperator": "AND"
          },
          "set": [
            "A"
          ]
        }
      ],
      "targetProducts": [
        {
          "kind": "SKU",
          "value": "*",
          "operator": "IN",
          "discountId": 1
        }
      ],
      "condition": [
        "620d84a715f2d00001234567"
      ]
    }
  ],
  "startDate": "2019-08-24T14:15:22Z",
  "endDate": "2019-08-25T14:15:22Z",
  "isExclusive": true,
  "type": "PRODUCT",
  "stackingType": "STACKABLE",
  "level": 1,
  "termsAndConditions": [
    {
      "title": "Terms Applied",
      "description": "Items cannot be exchanged"
    }
  ],
  "promotionMessages": [
    {
      "title": "Buy 1 get 1 free",
      "message": "Offer valid at participating stores through September 5, 2023.",
      "pages": [
        "PDP",
        "Cart"
      ],
      "locales": [
        "en-CA",
        "fr-CA"
      ]
    }
  ],
  "proximityMessages": [
    {
      "threshold": 1,
      "localizedMessages": [
        {
          "locales": [
            "<string>"
          ],
          "message": "<string>"
        }
      ]
    }
  ],
  "shipmentMethodIds": [
    1000001
  ],
  "eligiblePriceList": [
    10000056
  ],
  "limits": [
    {
      "kind": "ORDER",
      "value": 2
    }
  ],
  "note": "Independence day sale!",
  "createdAt": "2019-08-20T14:15:22Z",
  "updatedAt": "2019-08-20T14:15:22Z"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-site-context
string
required

The x-site-context header is a JSON object that contains information about the source you wish to pull from. The mandatory account is the 24 character identifier found in Copilot. The channel (Sales channel ID), stage (environment name), and date attributes can be used to further narrow the scope of your data source.

Example:

"{\"date\": \"2023-01-01T00:00:00.000Z\", \"channel\": 12, \"account\": \"1234abcd5678efgh9ijklmno\",\"stage\":\"production\"}"

Body

application/json

Following example shows creation of a promotion to get 10% off on any item sold with quantity 2 . If type is PRODUCT and kind is SKU, value as * indicates that all products are selected for the discount to be applied.

​
title
string
required

Promotion title

Required string length: 3 - 120
Example:

"CREATE PROMO"

​
promo
object[]
required
​
startDate
string
required

Start date of the promotion

Example:

"2019-08-24T14:15:22Z"

​
endDate
string
required

End date of the promotion

Example:

"2019-08-25T14:15:22Z"

​
isExclusive
boolean
required

A flag indicating whether a coupon can be stacked with an existing promotion. Set it to true to prevent the coupon from being applied to items that already have promotions and false to allow coupon to be applied with existing promotions.

Example:

true

​
type
enum<string>
required

Promotion type.<br /> Product: SKU promotion. Promotion or discount on SKUs based on the value mentioned in discount object<br />CART: Cart promotion. Promotion or discount on minimum order amount of cart based on the ORDER_VALUE that is set in condition object<br />QUANTITY: Quantity promotion provides discounts on items based on the quantity requirement set in the promotion<br />BOGO: Buy One Get One promotion provides discounts based on the Buy conditions and Get discounts<br />SHIPPING: Shipping promotion provides discounts on the shipping cost<br />BUYGET: BuyGet promotion specifies the Buy conditions and Get discounts<br />SPEND_GET: SpendGet promotion can specify the requirement of cart order value and the corresponding Get discounts

Available options:
PRODUCT,
CART,
QUANTITY,
BOGO,
SHIPPING,
BUYGET,
SPEND_GET
Example:

"PRODUCT"

​
buyOperator
enum<string>
default:OR

It is used to define operator between different Buy conditions (different conditions as mentioned in the condition object)

Available options:
AND,
OR
Example:

"OR"

​
stackingType
enum<string>

Defines the rules for how a promotion can be combined with other promotions. This field determines whether a specific promotion can be applied in conjunction with other active promotions during a transaction or if it must be used exclusively. Possible values: - STACKABLE: This promotion can be combined with other stackable promotions, allowing multiple discounts to be applied together. The order in which stackable promotions are applied is determined by the level field, with promotions having a higher priority (lower numeric value) being applied before those with a lower priority.

  • EXCLUSIVE: This promotion cannot be combined with any other promotions. The level field is used to determine which exclusive promotion will be evaluated and applied first. Once an exclusive promotion is applied, no other promotions can be used in the same transaction.
  • TYPE_EXCLUSIVE: This promotion cannot be combined with other promotions of the same type. The level field is used to determine which promotion within the same type will be evaluated and applied first.
  • UNIVERSAL: This promotion can be combined with any other promotions without restrictions. Universal promotions will be evaluated last. We don't need to define level for this type.
Available options:
STACKABLE,
EXCLUSIVE,
TYPE_EXCLUSIVE,
UNIVERSAL
Example:

"STACKABLE"

​
level
integer

The promotion execution order. Promotion types are assigned default execution orders. Initial evaluation begins with level 1 promotions. The result of level 1 is used as the base price for level 2. Similarly, the result of level 2 becomes the base price for level 3, and so on.

Example:

1

​
termsAndConditions
object[]
​
promotionMessages
object[]

Message description for the promotion

​
proximityMessages
object[]
​
shipmentMethodIds
string[]

The IDs of the shipping methods. They are required for promotions related to shipping.

​
eligiblePriceList
number[]

IDs of the price lists to which this promotion is applied

​
limits
object[]

Array of limits for the promotion to be applied

​
note
string

Promotion note or description

Example:

"Independence day sale!"

​
additionalAttributes
object[]

A placeholder for additional attributes, in key-value pairs.

Details of additional attributes.

Response

200
application/json
OK
​
_id
string

A 24-character system-generated promotion ID.

Example:

"abcdefg1ee7ce20123456789"

​
promoId
number

A unique identifier of the promotion, for external use.

Example:

100013

​
promoCodes
string[]

A list of coupon codes that are applicable only for coupons. For coupons, the response includes promo codes associated with the coupon. For promotions, the response includes an empty array.

Example:
["SUMMER100", "SUMMER20"]
​
state
enum<string>

Promotion status. <br /> ACTIVE indicates that the promotion is applied to SKUs or items for which it is set as Active. Active promotions cannot be disabled.<br />SCHEDULED indicates that the promotion is scheduled to be applied to SKUs or items based on the defined start date.<br />DISABLED indicates that the promotion is set as disabled and is not in use. Only Disabled promotions can be enabled.<br />EXPIRED indicates that the promotion is stopped by setting the expiration date. That is, the start date and end date as the current date. Only those promotions that are not expired can be enabled.

Available options:
ACTIVE,
SCHEDULED,
DISABLED,
EXPIRED
Example:

"SCHEDULED"

​
isImplicit
boolean

A flag indicating whether an offer is applied automatically. Set it to true for promotions, which should be applied automatically and false for coupons, which must be applied explicitly.

Example:

true

​
title
string

Title of the promotion

Example:

"CREATE PROMO"

​
buyOperator
enum<string>
default:OR

It is used to define operator between different Buy conditions (different conditions as mentioned in the condition object)

Available options:
AND,
OR
Example:

"OR"

​
promo
object[]
​
startDate
string

Start date of the promotion

Example:

"2019-08-24T14:15:22Z"

​
endDate
string

End date of the promotion

Example:

"2019-08-25T14:15:22Z"

​
isExclusive
boolean

A flag indicating whether a coupon can be stacked with an existing promotion. Set it to true to prevent the coupon from being applied to items that have promotions and false to allow coupon to be applied with existing promotions.

Example:

true

​
type
enum<string>

Promotion type.<br /> Product: SKU promotion. Promotion or discount on SKUs based on the value mentioned in discount object<br />CART: Cart promotion. Promotion or discount on cart amount based on the ORDER_VALUE that is set in condition object<br />QUANTITY: Quantity promotion provides discounts based on the quantity requirement set in the promotion<br />BOGO: Buy One Get One promotion provides discounts based on the Buy conditions and Get discounts<br />SHIPPING: Shipping promotion provides discounts on the shipping cost<br />BUYGET: BuyGet promotion specifies the Buy conditions and Get discounts<br />SPEND_GET: SpendGet promotion can specify the requirement of cart order value and the corresponding Get discounts

Available options:
PRODUCT,
CART,
QUANTITY,
BOGO,
SHIPPING,
BUYGET,
SPEND_GET
Example:

"PRODUCT"

​
stackingType
enum<string>

Defines the rules for how a promotion can be combined with other promotions. This field determines whether a specific promotion can be applied in conjunction with other active promotions during a transaction or if it must be used exclusively. Possible values: - STACKABLE: This promotion can be combined with other stackable promotions, allowing multiple discounts to be applied together. The order in which stackable promotions are applied is determined by the level field, with promotions having a higher priority (lower numeric value) being applied before those with a lower priority.

  • EXCLUSIVE: This promotion cannot be combined with any other promotions. The level field is used to determine which exclusive promotion will be evaluated and applied first. Once an exclusive promotion is applied, no other promotions can be used in the same transaction.
  • TYPE_EXCLUSIVE: This promotion cannot be combined with other promotions of the same type. The level field is used to determine which promotion within the same type will be evaluated and applied first.
  • UNIVERSAL: This promotion can be combined with any other promotions without restrictions. Universal promotions will be evaluated last. We don't need to define level for this type.
Available options:
STACKABLE,
EXCLUSIVE,
TYPE_EXCLUSIVE,
UNIVERSAL
Example:

"STACKABLE"

​
level
integer

The promotion execution order. Promotion types are assigned default execution orders. Initial evaluation begins with level 1 promotions. The result of level 1 is used as the base price for level 2. Similarly, the result of level 2 becomes the base price for level 3, and so on.

Example:

1

​
termsAndConditions
object[]
​
promotionMessages
object[]

Message description for the promotion

​
proximityMessages
object[]
​
shipmentMethodIds
string[]

Required for Shipping type promo to provide eligible shipment Methods

Shipping method IDs of the shipping methods to which promotion is applicable

​
eligiblePriceList
number[]

IDs of the price lists to which this promotion is applied

​
limits
object[]

Array of limits for the promotion to be applied

​
note
string

Promotion note or description

Example:

"Independence day sale!"

​
createdAt
string

Creation date of the record

Example:

"2019-08-20T14:15:22Z"

​
updatedAt
string

Last updated date of the record

Example:

"2019-08-20T14:15:22Z"

Was this page helpful?