Skip to main content

Create Promotion Codes

POST 
/v2/promotions/:promotionID/codes

Use this endpoint to create promotion codes for a specific promotion.

note

When a promotion expires, the promotion codes attached to the promotion automatically become invalid. However, when you re-enable the expired promotion, the promotion codes attached to the promotion are deleted.

Request​

Path Parameters

    promotionID stringrequired

    The unique identifier of the promotion.

Header Parameters

    Authorization Bearerrequired

    The Bearer token required to get access to the API.

Body

    codes object[]
  • Array [
    • code string

    Specifies the string to use as a code for the promotion.

    consume_unit string

    Specifies whether the code is applied to a line item or cart. The options are per_item or per_cart. The default setting is per_cart, which is applied at cart level. The per_item setting specifies how many times a buyer can use a promotion code on promotion items in a cart. For example, in a store that offers 50% off on SKU1, but limits the maximum usage of the promotion code to two, buyer can apply the promotion to SKU1 up to 2 times if cart has two quantities of SKU1. The third SKU1 is sold for regular price. The code usage is applied at checkout. You must set the automatic setting to false and create a code for this promotion to work.

    user string

    Specifies a string that specifies the users who can use the code. You can use the customer object ID or an array of customer object IDs. For more information, see the Create a customer section. Additionally, you could pass any identifying string to the promotions service that identifies a user.

    uses number

    Specifies the number of times the code can be used. If no value is set, the customer can use the code any number of times.

  • ]
    • type string

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

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...