Elastic Path Promotion Jobs API

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