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 how a use of the generated codes is counted. per_checkout is the default, and the only supported value. With per_checkout, a code is used once for each checkout, regardless of the number of items in the cart. The deprecated per_application is now rejected with a 422 error.
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."
        }
    ]
}