Bulk Create Promotion Builder Codes

Use Promotion Jobs to bulk generate promotion codes. See Promotion Jobs for the workflow.

POST Bulk Create Promotion Codes

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

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_job.
job_type	Required	string	Specifies the job type. Possible values: code_generate, code_export.
name	Optional	string	Represents the name of the job. The maximum allowed length is 50.
parameters.number_of_codes	Required	integer	Specifies the number of codes to be generated. It cannot be greater than the maximum number of codes per promotion, which defaults at 1000.
parameters.max_uses_per_code	Optional	integer	Specifies the maximum number of usages of a code. If set to zero, you cannot use this promotion. If no value is set, it can be used unlimited times.
parameters.consume_unit	Optional	string	Specifies whether the code is consumed per application or per checkout. The options are per_application or per_checkout. The default setting is per_checkout. With per_checkout, the code is used once for each checkout, regardless of the number of items in the cart. When set to per_application, the code is used per application. For cart discounts, each application counts as one usage. For item discounts, each application to either a single quantity or a bundle is counted as one usage. For example, in a store that offers 50% off on SKU1, SKU2, and SKU3, and limits the maximum usage of the promotion code to two, a shopper can apply the promotion up to two quantities. If the cart contains two or more quantities of SKU1, the promotion is applied 2 times to SKU1, and other quantities and items are at the regular price. If the cart contains one quantity of SKU1, one quantity of SKU2, and one quantity of SKU3, the promotion is applied once to SKU1 and once to SKU2. The code usage is applied at checkout and the code is considered consumed at that point.
parameters.code_prefix	Optional	string	Indicates the prefix to include with the promotion code. For example, when the generated value is aa2b-3c4d and the prefix value is set as summer, the promotion code becomes summer-aa2b-3c4d.
parameters.code_length	Optional	string	Specifies the code length, which ranges from 8 to 16 characters. The default code length is eight characters, and a dash is added after every four characters in the code. For example, aa2b-3c4d.

Request Example

curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/jobs \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data":{
        "type": "promotion_codes",
        "job_type": "code_generate",
        "name": "Demo bulk code generate",
        "parameters": {
            "number_of_codes": 100,
            "max_uses_per_code": 1,
            "consume_unit": "per_checkout",
            "code_prefix":"summer-",
            "code_length": 8
        }
    }
  }

Response Example

201 Created

{
    "data": {
        "type": "promotion_job",
        "id": "9bc1391c-1b65-419e-940e-66ed86c07001",
        "rule_promotion_id": "8c150382-b258-4c88-a2d4-b9ea0be74a07",
        "job_type": "code_generate",
        "name": "Demo bulk code generate",
        "parameters": {
            "number_of_codes": 100,
            "max_uses_per_code": 1,
            "consume_unit": "per_checkout",
            "code_prefix":"summer-",
            "code_length": 8
        },
        "status": "pending",
        "meta": {
            "timestamps": {
                "created_at": "2024-12-03T23:31:35.962680423Z",
                "updated_at": "2024-12-03T23:31:35.962680423Z"
            }
        }
    }
}

Errors

You cannot create more than one promotion job at the same time. If you attempt to do so, the following error will be returned:

{
    "errors": [
        {
            "status": "400",
            "title": "Too many jobs",
            "detail": "Only 1 pending or processing job is allowed per promotion."
        }
    ]
}