Create Promotion Codes

POST Create Promotion Codes

https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes

caution

The per_application value for consume_unit is not supported. Requests that set it are rejected with a 422 Unsupported consume unit error. Set consume_unit to per_checkout or omit the field. Existing promotion codes that have per_application work as configured.

note

• The promotion codes are case-insensitive.
• Multiple promotions can have the same code name. This means that different promotions can be identified using the same code names, allowing shoppers to apply a single coupon code that triggers multiple promotions. For more information see Duplicate Codes.

Parameters

Path parameters

Name	Required	Type	Description
promotionID	Required	string	The unique identifier of the rule promotion.

Headers

Name	Required	Type	Description
Authorization	Required	string	The Bearer token required to get access to the API.

Body

Name	Required	Type	Description
type	Required	string	Specifies the type of the resource. The type of resource for promotions is promotion_codes.
codes	Required	array	Specifies the code details in an array of objects.
codes[].code	Required	string	Specifies the string to use as a code for the promotion.
codes[].uses	Optional	integer	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.
codes[].user	Optional	string	Specifies the customer ID of the shopper who can use the code. For more information, see the Create a customer section.
consume_unit	Optional	string	Specifies how a use of the code is counted. per_checkout is the default, and the only supported value. With per_checkout, the code is used once for each checkout, regardless of the number of items in the cart. per_application is rejected with a 422 error.
is_for_new_shopper	Optional	boolean	A flag indicating whether the coupon is for first-time shoppers. If set to true, the discount will only apply if the shopper has never made a payment on any order in the store. If set to false or left unset, it will be a regular discount that applies to all shoppers. When this flag is set to true, the coupon cannot have usage limitations or be assigned to specific users.

Request Example

curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data":{
        "type": "promotion_codes",
        "codes": [
          {
          "code": "spring2024"
          },
          {
          "code": "summer2024",
          "consume_unit": "per_checkout"
          },
          {
          "code": "summer2024_limited",
          "consume_unit": "per_checkout",
          "uses": 5
          },
          {
          "code": "summer2024_memberOnly",
          "consume_unit": "per_checkout",
          "uses": 1,
          "user": "vip_shopper@email.com"
        }
    
      ]
    }
  }

Response Example

201 Created

{
    "data": [
        {
            "id": "0a985bab-8f20-4124-b832-2d39053dfc56",
            "code": "spring2024"
        },
        {
            "id": "519be2f4-1a8a-4d97-a292-f45e9f55e0dd",
            "code": "summer2024",
            "consume_unit": "per_checkout"
        },
        {
            "id": "bdf30707-d6f1-4914-9a17-bc1d45e62216",
            "code": "summer2024_limited",
            "uses": 5,
            "max_uses": 5,
            "consume_unit": "per_checkout"
        },
        {
            "id": "95981144-dbde-4b1e-af7f-b6268af2925d",
            "code": "summer2024_memberOnly",
            "user": "vip_shopper@email.com",
            "uses": 1,
            "max_uses": 1,
            "consume_unit": "per_checkout"
        }
    ]
}

Duplicate Codes

Multiple promotions can have the same code name. This means that different promotions can be identified using the same code names, allowing shoppers to apply a single coupon code that triggers multiple promotions.

Duplicate promotion codes are allowed among promotions in the store, regardless of their enabled or disabled status and validity dates. However, duplicate codes cannot be created within the same promotion. Even when codes are duplicated, they can serve different purposes. For example, one code may have limited use, while another code with the same name can have unlimited use.

When creating codes, a list of duplicated codes is returned:

"messages": [
        {
            "source": {
                "type": "promotion_codes",
                "codes": [
                    "spring2024",
                    "summer2024"
                ]
            },
            "title": "Duplicate code names",
            "description": "Code names duplicated in other promotions"
        }
    ]

Errors

You cannot create promotion codes for automatic promotions. The following error is returned if you attempt to do so:

{
    "errors": [
        {
            "status": "422",
            "title": "No codes allowed",
            "detail": "Cannot add codes to automatic promotion"
        }
    ]
}

The following error is returned if you attempt to create a promotion code that already exists in the same rule promotion:

{
    "errors": [
        {
            "status": "422",
            "title": "Duplicate code",
            "detail": "Promotion code already in use"
        }
    ]
}