openapi: 3.1.0 info: version: 25.1126.6886238 x-version-timestamp: 2025-11-26 19:10:23+00:00 title: Addresses Introduction Account Addresses Promotion Jobs API description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour. You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token. ' contact: name: Elastic Path url: https://www.elasticpath.com email: support@elasticpath.com license: url: https://elasticpath.dev name: MIT servers: - url: https://useast.api.elasticpath.com description: US East - url: https://euwest.api.elasticpath.com description: EU West security: - BearerToken: [] tags: - name: Promotion Jobs description: 'Use Jobs API to initiate a job within a promotion. Jobs operate asynchronously and have a different status based on their progress. The following are the job statuses: - `pending`: Commerce has received the request but is currently busy processing other requests. - `processing`: Commerce has initiated processing the job. - `completed`: The job is successfully completed. - `failed`: The job has failed. - `cancelling`: The job is currently in the process of being canceled. You need to wait for the cancellation process to complete. This occurs prior to the `cancelled` status. For example, if you cancel a big `code_generate` job, it may take some time for the cancellation to complete since part of the cancellation process involves deleting the generated codes. - `cancelled` : The job request is canceled. ![Promotion Job Statuses Workflow](/assets/job_status_workflow.png) ### Characteristics of Jobs - You can only initiate one job at a time within a promotion. If you want to run another job for the same promotion, you must wait until the previous job is `completed` or `failed`. However, you can create new jobs for different promotions even if there are `pending` jobs in other promotions. - If you intend to manage promotions with more than 10,000 codes per promotion, we recommend [exporting codes](/docs/api/promotions/create-a-promotion-job) for viewing purposes instead of attempting to view them within Commerce Manager. This recommendation is made due to our enforced maximum page offset limit of 10,000. Altering the page_offset_limit value poses potential performance risks to the platform. - A `code_generate` job is initiated even if the maximum allowable number of codes for the promotion has been reached. However, when processed, this job will fail. To view the status of this failed job, you can only do so by passing [GET Jobs](/docs/api/promotions/get-promotion-jobs) request. - A limited number of jobs can be processed at a time. Jobs are queued and processed sequentially, one after the other. You can expect a certain delay before job processing. ' paths: /v2/promotions/{promotionID}/jobs: parameters: - $ref: '#/components/parameters/Authorization' get: summary: Get Promotion Jobs description: "Retrieves the list of jobs for a specific promotion.\n\nIn the response example, you can see the `result.generated` field, which indicates the number of codes generated during the job processing. Additionally, you may also see the optional `result.deleted` field, indicating the number of codes deleted during the job cancellation. The parameters and result objects are shown only when `job_type` is `code_generate`.\n\n### Filtering\n\nThe following operators and attributes are available when filtering on this endpoint.\n\n| Attribute | Type | Operator | Example |\n| ----------| ----- | -------- | ------ |\n| `job_type` | `string` | `eq` | `eq(job_type, code_export)` |\n| `status` | `string` | `eq` | `eq(status, complete)` |\n\n### Errors\n\nIf an error occurs during job processing, the response includes an optional error field. For example, when you `GET` promotion jobs, the following response shows the details within the error field if an error occurred during job processing.\n\n ```json\n{\n \"data\": [\n {\n \"type\": \"promotion_job\",\n \"id\": \"84d86114-a92d-4c34-92f1-3e36ef6cabeb\",\n \"promotion_id\": \"ad386702-e780-42c6-b190-0527ad768917\",\n \"job_type\": \"code_generate\",\n \"name\": \"job\",\n \"parameters\": {\n \"number_of_codes\": 1000,\n \"consume_unit\": \"per_cart\",\n \"max_uses_per_code\": 1,\n \"code_length\": 8,\n \"code_prefix\": \"promo-\"\n },\n \"status\": \"failed\",\n \"error\": \"codes limit exceeded\",\n \"meta\": {\n \"timestamps\": {\n \"created_at\": \"2023-12-06T13:52:29.587Z\",\n \"updated_at\": \"2023-12-06T13:54:49.133Z\"\n }\n }\n }\n ],\n \"links\": {\n \"current\": \"https://useast.api.elasticpath.com/v2/promotions/ad386702-e780-42c6-b190-0527ad768917/jobs?page[offset]=0&page[limit]=25\",\n \"first\": \"https://useast.api.elasticpath.com/v2/promotions/ad386702-e780-42c6-b190-0527ad768917/jobs?page[offset]=0&page[limit]=25\",\n \"last\": \"https://useast.api.elasticpath.com/v2/promotions/ad386702-e780-42c6-b190-0527ad768917/jobs?page[offset]=0&page[limit]=25\",\n \"prev\": \"https://useast.api.elasticpath.com/v2/promotions/ad386702-e780-42c6-b190-0527ad768917/jobs?page[offset]=0&page[limit]=25\",\n \"next\": \"https://useast.api.elasticpath.com/v2/promotions/ad386702-e780-42c6-b190-0527ad768917/jobs?page[offset]=0&page[limit]=25\"\n },\n \"meta\": {\n \"page\": {\n \"limit\": 25,\n \"offset\": 0,\n \"current\": 1,\n \"total\": 1\n },\n \"results\": {\n \"total\": 1\n }\n }\n}\n```\n" tags: - Promotion Jobs parameters: - name: promotionID in: path required: true schema: type: string description: The unique identifier of a promotion. - name: filter in: query required: false schema: type: string description: Specifies the filter attributes. responses: '200': $ref: '#/components/responses/PromotionJobsListResponse' security: - bearerAuth: [] post: summary: Create a Promotion Job description: Use this endpoint to create an asynchronous job to generate codes and export promotion codes. tags: - Promotion Jobs parameters: - name: promotionID in: path required: true schema: type: string description: The unique identifier of a promotion. requestBody: required: true content: application/json: schema: type: object properties: type: description: Must be set to `promotion_job`. type: string example: promotion_job job_type: description: Specifies the type of task you want to run. For example, `code_generate` to generate codes or `code_export` to export codes. type: string enum: - code_generate - code_export name: type: string description: Represents the name of the job. The maximum allowed length is 50. maxLength: 50 parameters: type: object properties: number_of_codes: type: integer description: Specifies the number of codes to be generated. It cannot be greater than the maximum number of codes per promotion, which defaults at 1000. maximum: 1000 max_uses_per_code: type: integer description: 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. consume_unit: type: string description: Specifies whether the usage limitation is at the item-level or cart-level. enum: - per_item - per_cart code_prefix: type: string description: 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*. code_length: type: integer description: 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*. examples: generate-promotion-codes: summary: Generate Promotion Codes Job value: type: promotion_job job_type: code_generate name: Summer Sale Job parameters: number_of_codes: 1 max_uses_per_code: 1 consume_unit: per_cart code_prefix: Summer- code_length: 10 export-promotion-codes: summary: Export Promotion Codes Job value: type: promotion_job job_type: code_export name: Export Codes Job responses: '201': $ref: '#/components/responses/PromotionJobCreatedResponse' security: - bearerAuth: [] /v2/promotions/{promotionID}/jobs/{jobID}/cancel: parameters: - $ref: '#/components/parameters/Authorization' post: summary: Cancel a Job description: Cancels an asynchronous job whose status is pending or processing. tags: - Promotion Jobs parameters: - name: promotionID in: path required: true schema: type: string description: The unique identifier of a promotion. - name: jobID in: path required: true schema: type: string description: The unique identifier of a job to be canceled. responses: '200': $ref: '#/components/responses/PromotionJobCanceledResponse' security: - bearerAuth: [] /v2/promotions/{promotionID}/jobs/{jobID}/file: parameters: - $ref: '#/components/parameters/Authorization' get: summary: Get Promotion Code Exported File description: Retrieves exported codes in a CSV format. tags: - Promotion Jobs parameters: - name: promotionID in: path required: true schema: type: string description: The unique identifier of a promotion. - name: jobID in: path required: true schema: type: string description: The unique identifier of a job associated with the file. responses: '200': $ref: '#/components/responses/PromotionCodeExportedFileResponse' security: - bearerAuth: [] components: parameters: Authorization: name: Authorization in: header description: The Bearer token required to get access to the API. required: true schema: type: string format: Bearer responses: PromotionJobsListResponse: description: Successful response content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/PromotionJob' PromotionJobCanceledResponse: description: Job canceled successfully content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PromotionJob' PromotionCodeExportedFileResponse: description: Successful response content: application/json: schema: type: object properties: href: type: string description: URL to download the CSV file. PromotionJobCreatedResponse: description: Promotion job created content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PromotionJob' schemas: PromotionJob: type: object properties: id: type: string description: A unique ID generated when a job is created. type: description: Always `promotion_job`. type: string example: promotion_job promotion_id: description: A unique ID of a promotion. type: string job_type: description: The type of job you want to run. For example, `code_generate` to generate codes or `code_export` to export codes. type: string name: description: The name of the job. The maximum length allowed is 50 characters. type: string parameters: type: object status: description: The status of the job. See [Overview](/docs/api/promotions/promotion-jobs). type: string meta: type: object properties: timestamps: type: object properties: created_at: description: The creation date of the job. type: string format: date-time updated_at: description: The last updated date of the job. type: string format: date-time securitySchemes: BearerToken: type: http scheme: bearer