Get a Promotion

GET 
/v2/promotions/:promotionID

Retrieves a promotion.

Request

Path Parameters

promotionID stringrequired

The ID of the promotion.

Header Parameters

Authorization Bearerrequired

The Bearer token required to get access to the API.

Responses

200

OK

application/json

Schema

Schema

data object

oneOf

Data.CartFixedDiscountPromotion

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

Data.AttributeObject

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.

Data.NodesObject

node object

values string[]

Specifies unique identifiers of the nodes to be excluded from the promotion.

]

]

Data.CartPercentDiscountPromotion

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 [

percentage numberrequired

Specifies the discount percentage of the cart total value. For example, 10 represents 10% discount of the cart value of $100. You can add up to six decimal places for the discount percentage to be applied for the promotion.

currency stringrequired

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

]

conditions object

or object[]

Array [

and object[]

Array [

oneOf

Data.AttributeObject

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.

Data.NodesObject

node object

values string[]

Specifies unique identifiers of the nodes to be excluded from the promotion.

]

]

Data.ItemFixedDiscountPromotion

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.

targets string[]

Specifies the product SKUs or unique identifiers of the products included in the promotion. Set "targets:all" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define schema.targets, schema.target_nodes or schema.target_attributes, or all three of them to qualify for this promotion.

target_nodes string[]

Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define schema.target_nodes without defining the schema.targets if the promotion is intended for a certain node. You cannot define "targets":"all" and schema.target_nodes within the same schema. This will result in a validation error.

target_attributes object[]

Array [

template string

Specifies the name of the template slug to be included in a promotion.

field string

Specifies the unique slug identifier for the field to be included in 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.type. For example, you can specify any color in the value if you indicate color in the attributes.field.

]

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

Data.AttributeObject

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.

Data.NodesObject

node object

values string[]

Specifies unique identifiers of the nodes to be excluded from the promotion.

]

]

Data.ItemPercentDiscountPromotion

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.

targets string[]

Specifies the product SKUs or unique identifiers of the products included in the promotion. Set "targets:all" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define schema.targets, schema.target_nodes or schema.target_attributes, or all three of them to qualify for this promotion.

target_nodes string[]

Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define schema.target_nodes without defining the schema.targets if the promotion is intended for a certain node. You cannot define "targets":"all" and schema.target_nodes within the same schema. This will result in a validation error.

target_attributes object[]

Array [

template string

Specifies the name of the template slug to be included in a promotion.

field string

Specifies the unique slug identifier for the field to be included in 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.type. For example, you can specify any color in the value if you indicate color in the attributes.field.

]

conditions object

or object[]

Array [

and object[]

Array [

oneOf

Data.AttributeObject

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.

Data.NodesObject

node object

values string[]

Specifies unique identifiers of the nodes to be excluded from the promotion.

]

]

percent integerrequired

Specifies the discount percentage to be applied to the targeted SKU price. For example, 10% discount on a product SKU priced at $100. You can specify the discount percentage with up to six decimal places.

Data.XForYDiscountPromotion

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.

targets string[]

Specifies the product SKUs or unique identifiers of the products included in the promotion. Set "targets:all" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define schema.targets, schema.target_nodes or schema.target_attributes, or all three of them to qualify for this promotion.

target_nodes string[]

Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define schema.target_nodes without defining the schema.targets if the promotion is intended for a certain node. You cannot define "targets":"all" and schema.target_nodes within the same schema. This will result in a validation error.

target_attributes object[]

Array [

template string

Specifies the name of the template slug to be included in a promotion.

field string

Specifies the unique slug identifier for the field to be included in 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.type. For example, you can specify any color in the value if you indicate color in the attributes.field.

]

conditions object

or object[]

Array [

and object[]

Array [

oneOf

Data.AttributeObject

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.

Data.NodesObject

node object

values string[]

Specifies unique identifiers of the nodes to be excluded from the promotion.

]

]

x integerrequired

Specifies the X value for the promotion.

y integerrequired

Specifies the Y value for the promotion.

Data.XForAmountDiscountPromotion

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.

targets string[]

Specifies the product SKUs or unique identifiers of the products included in the promotion. Set "targets:all" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define schema.targets, schema.target_nodes or schema.target_attributes, or all three of them to qualify for this promotion.

target_nodes string[]

Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define schema.target_nodes without defining the schema.targets if the promotion is intended for a certain node. You cannot define "targets":"all" and schema.target_nodes within the same schema. This will result in a validation error.

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

Data.AttributeObject

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.

Data.NodesObject

node object

values string[]

Specifies unique identifiers of the nodes to be excluded from the promotion.

]

]

x integerrequired

Specifies the X value for the promotion.

Data.FixedBundleDiscountPromotion

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.

]

requirements object[]required

Array [

targets string[]required

Specifies an array of required product SKUs or IDs for the bundle discount promotion.

quantity integerrequired

Specifies the quantities of products to be applied for the promotion.

]

Data.FreeGiftPromotion

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.

requirements object[]required

Array [

targets string[]required

Specifies an array of required product SKUs or IDs for the bundle discount promotion.

quantity integerrequired

Specifies the quantities of products to be applied for the promotion.

]

gifts string[]required

Specifies all the gift items that a shopper can avail when they qualify for the promotion. The gift quantity applies to each specified item. For example, if the promotion includes giftA and giftB, shopper can avail both the gifts if the cart qualifies for the gift promotion. If the cart qualifies for two gift promotions, the shopper can use two giftA and two giftB.

auto_add_free_gift boolean

When set to true, free gift items are automatically added to the shopping cart for all the eligible products. Default is false.

Example (from schema)

{
  "data": {
    "type": "string",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "description": "string",
    "promotion_type": "fixed_discount",
    "enabled": true,
    "automatic": true,
    "start": "string",
    "end": "string",
    "min_cart_value": {},
    "max_applications_per_cart": 0,
    "schema": {
      "target_catalogs": [
        "string"
      ],
      "currencies": [
        {
          "amount": 0,
          "currency": "string"
        }
      ],
      "conditions": {
        "or": [
          {
            "and": [
              {
                "attribute": {
                  "template": "string",
                  "field": "string",
                  "type": "string",
                  "value": "string"
                }
              },
              {
                "node": {
                  "values": [
                    "string"
                  ]
                }
              }
            ]
          }
        ]
      }
    }
  }
}

401

Unauthorized

application/json

Schema

Schema

detail string
status string
title string

Example (from schema)

[
  null
]

Example

{
  "errors": {
    "status": 401,
    "title": "Unauthorized"
  }
}

Loading...