--- title: "Create promotion" method: POST path: "/api-offers/promo/create" tags: ["Promotion"] --- # Create promotion `POST /api-offers/promo/create` ## Request - Base URL: `https://live.copilot.fabric.inc` - URL: `https://live.copilot.fabric.inc/api-offers/promo/create` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Enables you to create a promotion ## Headers - `x-site-context` string, required ## Request body - CreatePromo: 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 - `buyOperator` 'AND' | 'OR': It is used to define operator between different *Buy* conditions (different conditions as mentioned in the `condition` object) - `promo` object[], required - `discount` Discount[], required: Discount information - `unit` '%OFF' | 'AMOUNT_OFF' | 'FIXED', required: Unit of discount; represents whether the discount is in percentage or by a certain amount - `value` number, required: Discount value to be applied - `discountId` string: Discount ID to link `discount` and `targetProduct`, and is required for BuyGet and SpendGet type promotions - `autoAdd` boolean: To indicate if the evaluation API (from Dynamic Pricing Engine) should suggest free items. Currently used for BuyGet and SpendGet type promotions. - `ON` object, required: Indicates kind of products promotion is applied on. - `kind` 'SKU' | 'CART' | 'SERVICE' | 'SERVICE_CART', required: SKU if discount is on products
`SERVICE` if discount is on an SKU shipping cost
`SERVICE_CART` if discount is on cart shipping cost - `value` union, required - string - object[] - `quantity` number: Quantity of items to be sold for the discount to be applied. It is required when `type` is SPEND_GET, BUYGET, BOGO (Buy One Get One) - `includeOperator` 'AND' | 'OR': Select the `AND` or `OR` condition to include products in a promotion.
Use the `OR` condition to apply a single rule for product inclusion.
Use the `AND` condition to apply multiple rules for product inclusion. - `excludeOperator` 'AND' | 'OR': Select the `AND` or `OR` condition to exclude products from a promotion.
Use the `OR` condition to apply a single rule for product exclusion.
Use the `AND` condition to apply multiple rules for product exclusion. - `set` string[]: It is used to create a group of items in a set so that you can easily apply promotions or coupons to the defined set of items. - `targetProducts` TargetProduct[], required: The products the discounts are applied to. - `kind` 'SKU' | 'CATEGORY' | 'ATTRIBUTE' | 'PRICE_KIND' | 'PREVIOUS_DISCOUNT', required: Selection of product type - `value` union, required: Value for the kind as defined above.
For `SKU`, value can be array of itemIds or array of SKU descriptions.
For `Category`, value can be array of category IDs or category descriptions.
For `Attribute`, value can be array of attribute objects, for example [{name: 'attribute-name', value:'attribute-value'}] - string: Description of the product. Here * indicates that all products are selected for the discount to be applied. - union[] - union - number: SKU ID. [1000000234, 1000000445] could be array of itemIds if you want to apply promotion on selected items - string: SKU description - `operator` 'IN' | 'NOT_IN' | 'EQUAL' | 'GREATER_THAN', required: The type of search operation. You can use multiple values separated by commas for the IN and NOT_IN operations. However, you can use only a single value for the EQUALS and GREATER_THAN operations. - `discountId` string: Discount ID to link discount and targetProduct, and is required for BuyGet and SpendGet promotions - `condition` PromoCondition[], required: Conditions for the promotion to be qualified - `operator` 'AND' | 'OR', required: Conditional operator to be applied between each object of conditions array - `includeOperator` 'AND' | 'OR': Select the `AND` or `OR` condition to include products in a promotion.
Use the `OR` condition to apply a single rule for product inclusion.
Use the `AND` condition to apply multiple rules for product inclusion. - `excludeOperator` 'AND' | 'OR': To exclude products from promotions, select the `AND` or `OR` operator for product exclusion rules.
Use the `OR` operator to apply a single rule for product exclusion.
Use the `AND` operation to apply multiple rules for product exclusion. - `conditions` Condition[], required - `key` 'SKU' | 'QUANTITY' | 'CATEGORY' | 'ATTRIBUTE' | 'PRICE_KIND' | 'CHANEL' | 'ORDER_VALUE' | 'USER_SEGMENT' | 'USER_KIND', required - `value` union, required - string: The value corresponding to the `key`. - union[] - union - … - `operator` 'NOT_EQUAL' | 'EQUAL' | 'GREATER_THAN' | 'LESS_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN_OR_EQUAL_TO' | 'NOT_IN' | 'IN', required: Defines the condition for `key` and `value` set passed in the object. For example, IN indicates that the `key` and `value` set are included for promotion to be applied. - `set` 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z': It is used to create a group of items in a set so that you can easily apply promotions or coupons to the defined set of items. - `startDate` string, date-time, required: Start date of the promotion - `endDate` string, date-time, required: End date of the promotion - `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. - `type` 'PRODUCT' | 'CART' | 'QUANTITY' | 'BOGO' | 'SHIPPING' | 'BUYGET' | 'SPEND_GET', required: Promotion type.
**Product:** SKU promotion. Promotion or discount on SKUs based on the value mentioned in *discount* object
**CART:** Cart promotion. Promotion or discount on minimum order amount of cart based on the *ORDER_VALUE* that is set in *condition* object
**QUANTITY:** Quantity promotion provides discounts on items based on the quantity requirement set in the promotion
**BOGO:** Buy One Get One promotion provides discounts based on the Buy conditions and Get discounts
**SHIPPING:** Shipping promotion provides discounts on the shipping cost
**BUYGET:** BuyGet promotion specifies the Buy conditions and Get discounts
**SPEND_GET:** SpendGet promotion can specify the requirement of cart order value and the corresponding Get discounts - `stackingType` 'STACKABLE' | 'EXCLUSIVE' | 'TYPE_EXCLUSIVE' | 'UNIVERSAL': 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. - `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. - `termsAndConditions` TermsAndConditions[] - `title` string: Title of the terms and conditions - `description` string: Description of the terms and conditions - `promotionMessages` PromotionMessage[] - `title` string: Message name - `message` string: Message description - `pages` string[]: Types of web pages where the message will be displayed - `locales` string[]: Locales in which promotion message will be displayed. Locale is a set of language or country-based preferences for user interface. - `proximityMessages` ProximityMessage[] - `threshold` integer: The proximity threshold value. - `localizedMessages` object[] - `locales` string[] - `message` string: The localized message for the specified locales. - `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 - `kind` string, required: Kind of limit for the promotion to be applied - `value` number, required: Value of limit for the promotion to be applied - `note` string: Promotion note or description - `additionalAttributes` object[]: A placeholder for additional attributes, in key-value pairs. - `key` string: The attribute name. - `value` union: The attribute value or values corresponding to the `key`. - string: The value of the additional attribute. - string[] - `attributeId` number: A unique identifier of the attribute. ## Response `200` OK - PromoResponse - `_id` string: A 24-character system-generated promotion ID. - `promoId` number: A unique identifier of the promotion, for external use. - `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. - `state` 'ACTIVE' | 'SCHEDULED' | 'DISABLED' | 'EXPIRED': Promotion status.
`ACTIVE` indicates that the promotion is applied to SKUs or items for which it is set as *Active*. Active promotions cannot be disabled.
`SCHEDULED` indicates that the promotion is scheduled to be applied to SKUs or items based on the defined start date.
`DISABLED` indicates that the promotion is set as *disabled* and is not in use. Only *Disabled* promotions can be enabled.
`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. - `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. - `title` string: Title of the promotion - `buyOperator` 'AND' | 'OR': It is used to define operator between different *Buy* conditions (different conditions as mentioned in the `condition` object) - `promo` object[] - `discount` Discount[]: Discount details - `unit` '%OFF' | 'AMOUNT_OFF' | 'FIXED', required: Unit of discount; represents whether the discount is in percentage or by a certain amount - `value` number, required: Discount value to be applied - `discountId` string: Discount ID to link `discount` and `targetProduct`, and is required for BuyGet and SpendGet type promotions - `autoAdd` boolean: To indicate if the evaluation API (from Dynamic Pricing Engine) should suggest free items. Currently used for BuyGet and SpendGet type promotions. - `ON` object, required: Indicates kind of products promotion is applied on. - `kind` 'SKU' | 'CART' | 'SERVICE' | 'SERVICE_CART', required: SKU if discount is on products
`SERVICE` if discount is on an SKU shipping cost
`SERVICE_CART` if discount is on cart shipping cost - `value` union, required - string - object[] - `quantity` number: Quantity of items to be sold for the discount to be applied. It is required when `type` is SPEND_GET, BUYGET, BOGO (Buy One Get One) - `includeOperator` 'AND' | 'OR': Select the `AND` or `OR` condition to include products in a promotion.
Use the `OR` condition to apply a single rule for product inclusion.
Use the `AND` condition to apply multiple rules for product inclusion. - `excludeOperator` 'AND' | 'OR': Select the `AND` or `OR` condition to exclude products from a promotion.
Use the `OR` condition to apply a single rule for product exclusion.
Use the `AND` condition to apply multiple rules for product exclusion. - `set` string[]: It is used to create a group of items in a set so that you can easily apply promotions or coupons to the defined set of items. - `targetProducts` TargetProduct[]: The products the discount is applied to. - `kind` 'SKU' | 'CATEGORY' | 'ATTRIBUTE' | 'PRICE_KIND' | 'PREVIOUS_DISCOUNT', required: Selection of product type - `value` union, required: Value for the kind as defined above.
For `SKU`, value can be array of itemIds or array of SKU descriptions.
For `Category`, value can be array of category IDs or category descriptions.
For `Attribute`, value can be array of attribute objects, for example [{name: 'attribute-name', value:'attribute-value'}] - string: Description of the product. Here * indicates that all products are selected for the discount to be applied. - union[] - union - number: SKU ID. [1000000234, 1000000445] could be array of itemIds if you want to apply promotion on selected items - string: SKU description - `operator` 'IN' | 'NOT_IN' | 'EQUAL' | 'GREATER_THAN', required: The type of search operation. You can use multiple values separated by commas for the IN and NOT_IN operations. However, you can use only a single value for the EQUALS and GREATER_THAN operations. - `discountId` string: Discount ID to link discount and targetProduct, and is required for BuyGet and SpendGet promotions - `condition` string[]: List of linked condition IDs to the promotion - `startDate` string, date-time: Start date of the promotion - `endDate` string, date-time: End date of the promotion - `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. - `type` 'PRODUCT' | 'CART' | 'QUANTITY' | 'BOGO' | 'SHIPPING' | 'BUYGET' | 'SPEND_GET': Promotion type.
**Product:** SKU promotion. Promotion or discount on SKUs based on the value mentioned in *discount* object
**CART:** Cart promotion. Promotion or discount on cart amount based on the *ORDER_VALUE* that is set in *condition* object
**QUANTITY:** Quantity promotion provides discounts based on the quantity requirement set in the promotion
**BOGO:** Buy One Get One promotion provides discounts based on the Buy conditions and Get discounts
**SHIPPING:** Shipping promotion provides discounts on the shipping cost
**BUYGET:** BuyGet promotion specifies the Buy conditions and Get discounts
**SPEND_GET:** SpendGet promotion can specify the requirement of cart order value and the corresponding Get discounts - `stackingType` 'STACKABLE' | 'EXCLUSIVE' | 'TYPE_EXCLUSIVE' | 'UNIVERSAL': 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. - `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. - `termsAndConditions` TermsAndConditions[] - `title` string: Title of the terms and conditions - `description` string: Description of the terms and conditions - `promotionMessages` PromotionMessage[] - `title` string: Message name - `message` string: Message description - `pages` string[]: Types of web pages where the message will be displayed - `locales` string[]: Locales in which promotion message will be displayed. Locale is a set of language or country-based preferences for user interface. - `proximityMessages` ProximityMessage[] - `threshold` integer: The proximity threshold value. - `localizedMessages` object[] - `locales` string[] - `message` string: The localized message for the specified locales. - `shipmentMethodIds` string[]: Required for Shipping type promo to provide eligible shipment Methods - `eligiblePriceList` number[]: IDs of the price lists to which this promotion is applied - `limits` object[]: Array of limits for the promotion to be applied - `kind` string: Kind of limit for the promotion to be applied - `value` number: Value of limit for the promotion to be applied - `note` string: Promotion note or description - `createdAt` string, date-time: Creation date of the record - `updatedAt` string, date-time: Last updated date of the record ## Other responses - `400`: Bad request - `500`: Internal Server Error --- [API](https://skmtc.dev/fabric/apis/offers-v2.md) - [All operations](https://skmtc.dev/fabric/apis/offers-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/fabric/apis/offers-v2/revisions/da2bd742b9bc?raw)