Skip to main content

Create a Promotion

POST 
/v2/promotions

You can use this endpoint to create the following types of promotion:

  • Cart Fixed Discount Promotion
  • Cart Percent Discount Promotion
  • X for Y Discount Promotion
  • X for Amount Discount Promotion
  • Fixed Bundle Discount Promotion
  • Item Fixed Discount Promotion
  • Item Percent Discount Promotion
  • Free Gift Promotion

The schema object​

Promotions are defined by schemas that are used internally to verify promotions and calculate discounts. You must define a schema when you create the promotion. For more information, see the schema.exclude criteria and the targeting fields criteria.

The schema.exclude criteria​

When creating a promotion, you can specify when it should not be applied. The promotion will not be applied on any cart (or cart item, depending on the promotion type) that fulfills at least one of the schema.exclude criteria. The following criteria can be set to exclude items from a promotion:

  • schema.exclude.targets
  • schema.exclude.nodes
  • schema.exclude.attributes
  • schema.exclude.conditions

For example, if you want to create a promotion with value as SKU1 in schema.exclude.targets and and color yellow and size small in schema.exclude.attributes, then any products with SKU1 or the color yellow or the size small will be excluded from the promotion.

To exclude products from a promotion based on multiple conditions at the same time, use schema.exclude.conditions. For example, use schema.exclude.conditions to exclude items that are both yellow in color and small in size.

The targeting fields criteria​

When creating a promotion, you can also specify when it should be applied. To define the targeted products, use the following fields:

  • schema.target_catalogs
  • schema.targets
  • schema.target_nodes
  • schema.target_attributes
  • schema.target_conditions

The cart item's catalog is verified if you define the schema.target_catalogs field. If the item is in any of the targeted catalogs specified in schema.target_catalogs, the promotion will be applied. If the item is not in any of the catalogs, the promotion will not be applied.

Then, the cart item is verified to see if it fulfills at least one criteria of any of the four other targeting fields. In other words, the schema targeting fields such as schema.targets, schema.target_nodes, schema.target_attributes and schema.target_conditions create OR trageting conditions.

For example, if you create a promotion with values as SKU1 in schema.targets and color yellow and size small in schema.target_attributes, then it will be applied to any products with SKU1 or the color yellow or the size small.

To create a promotion that targets products based on multiple conditions at the same time, use schema.target_conditions. For example, use it to target items that are both yellow in color and small in size.

note

For Cart Fixed Discount Promotion and Cart Percent Discount Promotion, the cart item's catalog is verified if you define the schema.target_catalogs field. If the item is in any of the targeted catalogs specified in schema.target_catalogs, the promotion will be applied. If the item is not in any of the catalogs, the promotion will not be applied.

caution
  • Line-item discounts are only supported by the line calculation method. For more information about this method, see the Calculation Method section.
  • Hierarchy-based promotions are not supported for fixed bundle discount promotion and free gift promotion. To promote a bundle, create the bundle in Product Experience Manager, and then create a promotion for that bundle. For more information, see Bundles in Product Experience Manager.
  • For Free Gift Promotion, we recommend using auto_add_free_gift feature with automatic setting enabled. When automatic is set to true, it indicates that promotions are added automatically, and discounts are applied accordingly. If you enable the auto_add_free_gift, but do not enable the automatic setting, gift items will be added without discounts. In this case, shoppers need to apply coupon codes twice, first to add the gift item and then to apply the discount.

Request​

Header Parameters

    Authorization Bearerrequired

    The Bearer token required to get access to the API.

Body

    data object required
    oneOf
    type stringrequired

    Specifies the type of the resource. The type of resource for promotions is promotion.

    name stringrequired

    Specifies a name for the promotion.

    description stringrequired

    Specifies a description for the promotion.

    promotion_type stringrequired

    Possible values: [fixed_discount, percent_discount, item_fixed_discount, item_percent_discount, x_for_y, x_for_amount, bundle_fixed_discount, bundle_gift]

    Specifies the type of the promotion.

    enabled booleanrequired

    Specifies whether the promotion is enabled. The options are true or false, and the default setting is false.

    automatic booleanrequired

    Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to false. When this value is set to true, a code is autogenerated. If this value is set to false, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.

    start stringrequired

    Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.

    end stringrequired

    Specifies the end date and time of the promotion or the end date of the promotion.

    min_cart_value object

    Specifies an array of currency-value objects, min_cart_value[].currency and min_cart_value[].amount, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use max_discount_value for Cart Fixed Discount promotion and Item Fixed Discount promotion. If max_discount_value is greater than the fixed_discount value, the fixed_discount value is applied; otherwise the max_discount value is applied.

    max_applications_per_cart number

    Specifies the maximum number of application of a promotion per cart.

    schema objectrequired
    target_catalogs string[]

    Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.

    currencies object[]required
  • Array [
    • amount integerrequired

    Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.

    currency stringrequired

    Specifies a three-letter currency code. For example, USD.

  • ]
    • conditions object
    or object[]
  • Array [
    • and object[]
  • Array [
    • oneOf
    attribute object
    template string

    Specifies the name of the template slug to be excluded from a promotion.

    field string

    Specifies the unique slug identifier for the field excluded from a promotion.

    type string

    Specifies the type of the field, such as string, integer, boolean, float, or date.

    value string

    Specifies the value of the field that was specified in the attributes.field. For example, you can specify any color in the value if you indicate color in the attributes.field.

  • ]
  • ]

Responses​

Response Headers
    Schema
      data object
      oneOf
      type stringrequired

      Specifies the type of the resource. The type of resource for promotions is promotion.

      id uuidrequired
      name stringrequired

      Specifies a name for the promotion.

      description stringrequired

      Specifies a description for the promotion.

      promotion_type stringrequired

      Possible values: [fixed_discount, percent_discount, item_fixed_discount, item_percent_discount, x_for_y, x_for_amount, bundle_fixed_discount, bundle_gift]

      Specifies the type of the promotion.

      enabled booleanrequired

      Specifies whether the promotion is enabled. The options are true or false, and the default setting is false.

      automatic booleanrequired

      Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to false. When this value is set to true, a code is autogenerated. If this value is set to false, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.

      start stringrequired

      Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.

      end stringrequired

      Specifies the end date and time of the promotion or the end date of the promotion.

      min_cart_value object

      Specifies an array of currency-value objects, min_cart_value[].currency and min_cart_value[].amount, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use max_discount_value for Cart Fixed Discount promotion and Item Fixed Discount promotion. If max_discount_value is greater than the fixed_discount value, the fixed_discount value is applied; otherwise the max_discount value is applied.

      max_applications_per_cart number

      Specifies the maximum number of application of a promotion per cart.

      schema objectrequired
      target_catalogs string[]

      Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.

      currencies object[]required
    • Array [
      • amount integerrequired

      Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.

      currency stringrequired

      Specifies a three-letter currency code. For example, USD.

    • ]
      • conditions object
      or object[]
    • Array [
      • and object[]
    • Array [
      • oneOf
      attribute object
      template string

      Specifies the name of the template slug to be excluded from a promotion.

      field string

      Specifies the unique slug identifier for the field excluded from a promotion.

      type string

      Specifies the type of the field, such as string, integer, boolean, float, or date.

      value string

      Specifies the value of the field that was specified in the attributes.field. For example, you can specify any color in the value if you indicate color in the attributes.field.

    • ]
    • ]
    Loading...