Create a Rule Promotion Job

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

Creates an asynchronous job for a specific Rule Promotion. Jobs are used to generate or export promotion codes in bulk.

The following job types are supported:

• code_generate: Generates a batch of unique promotion codes.
• code_export: Exports all existing promotion codes as a downloadable CSV file.

Job processing occurs asynchronously. The job request is queued, and its status must be checked separately.

Job Processing Status

Jobs can have the following statuses:

• pending: Job is in the queue, waiting to be processed.
• processing: Job is actively being processed.
• completed: Job completed successfully.
• failed: Job encountered an error and did not complete.
• cancelling: Cancellation in progress (for long-running jobs).
• cancelled: Job was successfully cancelled.

Please refer to the OpenAPI examples section on this page for sample job creation requests.

Request

Path Parameters

uuid stringrequired

The unique identifier of the rule promotion.

application/json

Bodyrequired

typestring
Must be set to promotion_job.
Possible values: [promotion_job]
job_typestring
Specifies the type of task to run.
Possible values: [code_generate, code_export]
namestring
Represents the name of the job. The maximum allowed length is 50 characters.
Possible values: <= 50 characters
parameters object
number_of_codesinteger
Specifies the number of codes to be generated.
Possible values: <= 1000
max_uses_per_codeinteger
Specifies the maximum number of usages per code. If set to zero, you cannot use this promotion. If no value is set, it can be used unlimited times.
consume_unitstring
Specifies whether the code is consumed per application or 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.
Possible values: [per_application, per_checkout]
code_prefixstring
Prefix for generated promotion codes (e.g., SUMMER-).
code_lengthinteger
Code length.
Possible values: >= 8 and <= 16
Default value: 8

Responses

201

Promotion job created

application/json

Schema

Schema

data object
idstring
A unique ID generated when a job is created.
typestring
Always promotion_job.
Possible values: [promotion_job]
rule_promotion_idstring
A unique ID of a promotion.
job_typestring
The type of job you want to run. For example, code_generate to generate codes or code_export to export codes.
namestring
The name of the job. The maximum length allowed is 50 characters.
parametersobject
statusstring
The status of the job. Please see Overview.
errorstring
The error encountered during job execution, if applicable.
meta object
timestamps object
created_atdate-time
The creation date of the job.
updated_atdate-time
The last updated date of the job.
generate_result object
Represents the result of a promotion job, including the number of generated and deleted promotion codes.
• generated: Total number of successfully generated codes.
• deleted: Number of codes that were deleted during job cancellation, if applicable.
generatedinteger
Number of successfully generated promotion codes.
Example: 1000
deletedintegernullable
Number of codes deleted due to job cancellation.
Example: 50

Example (auto)

{
  "data": {
    "id": "string",
    "type": "promotion_job",
    "rule_promotion_id": "string",
    "job_type": "string",
    "name": "string",
    "parameters": {},
    "status": "string",
    "error": "string",
    "meta": {
      "timestamps": {
        "created_at": "2024-07-29T15:51:28.071Z",
        "updated_at": "2024-07-29T15:51:28.071Z"
      }
    },
    "generate_result": {
      "generated": 1000,
      "deleted": 50
    }
  }
}

400

Bad Request

application/json

Schema

Schema

errors object[]
Array [
statusstring
Example: 400
titlestring
Example: Too many jobs
detailstring
Example: Only 1 pending or processing job is allowed per promotion.
]

Example (auto)

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

TooManyJobsError

Error When Attempting to Create a Job While Another Job is Still Processing

• csharp
• curl
• dart
• go
• http
• java
• javascript
• kotlin
• c
• nodejs
• objective-c
• ocaml
• php
• powershell
• python
• r
• ruby
• rust
• shell
• swift

• HTTPCLIENT
• RESTSHARP

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://useast.api.elasticpath.com/v2/rule-promotions/:uuid/jobs");
request.Headers.Add("Accept", "application/json");
var content = new StringContent("{\n  \"type\": \"promotion_job\",\n  \"job_type\": \"code_generate\",\n  \"name\": \"string\",\n  \"parameters\": {\n    \"number_of_codes\": 0,\n    \"max_uses_per_code\": 0,\n    \"consume_unit\": \"per_application\",\n    \"code_prefix\": \"string\",\n    \"code_length\": 8\n  }\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Request Collapse all

Base URL

https://useast.api.elasticpath.com

Parameters

uuid — pathrequired

Body required

• Example (from schema)
• GenerateBulkPromotionCodes
• ExportPromotionCodes

{
  "type": "promotion_job",
  "job_type": "code_generate",
  "name": "string",
  "parameters": {
    "number_of_codes": 0,
    "max_uses_per_code": 0,
    "consume_unit": "per_application",
    "code_prefix": "string",
    "code_length": 8
  }
}

ResponseClear

Click the Send API Request button above and see the response here!