Elastic Path

Elastic Path Promotion Jobs API

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.

Documentation GitHub OpenAPI

Business capability

Discount & Promotion Management BC-440.30

Operations 4

GET /v2/promotions/{promotionID}/jobs Get Promotion Jobs #

POST /v2/promotions/{promotionID}/jobs Create a Promotion Job #

POST /v2/promotions/{promotionID}/jobs/{jobID}/cancel Cancel a Job #

GET /v2/promotions/{promotionID}/jobs/{jobID}/file Get Promotion Code Exported File #

Documentation

📖

Documentation

https://developer.elasticpath.com/api

Specifications

⚙

OpenAPI

https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/openapi/elastic-path-promotion-jobs-api-openapi.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/elastic-path-promotion-jobs-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Promotions Standard Introduction Promotion Jobs API
  description: Promotions Standard offer the flexibility to provide different types of discounts to all your customers or specific customers.
  contact:
    name: Elastic Path
    url: https://elasticpath.com
  license:
    name: MIT
    url: assets/LICENSE
  version: 26.0504.7552059
  x-version-timestamp: 2026-05-04 17:39:21+00:00
servers:
- url: https://useast.api.elasticpath.com
  description: US East Production Server
  variables: {}
- url: https://euwest.api.elasticpath.com
  description: EU West Production Server
  variables: {}
security:
- bearerAuth: []
tags:
- name: Promotion Jobs
  description: Use Jobs API to initiate a job within a promotion.
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.


        In 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`.


        ### Filtering


        The following operators and attributes are available when filtering on this endpoint.


        | Attribute | Type | Operator | Example |

        | ----------| ----- | -------- | ------ |

        | `job_type` | `string` | `eq` | `eq(job_type, code_export)` |

        | `status` | `string` | `eq` | `eq(status, complete)` |


        ### Errors


        If 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.


        ```json

        {

        "data": [

        {

        "type": "promotion_job",

        "id": "84d86114-a92d-4c34-92f1-3e36ef6cabeb",

        "promotion_id": "ad386702-e780-42c6-b190-0527ad768917",

        "job_type": "code_generate",

        "name": "job",

        "parameters": {

        "number_of_codes": 1000,

        "consume_unit": "per_cart",

        "max_uses_per_code": 1,

        "code_length": 8,

        "code_prefix": "promo-"

        },

        "status": "failed",

        "error": "codes limit exceeded",

        "meta": {

        "timestamps": {

        "created_at": "2023-12-06T13:52:29.587Z",

        "updated_at": "2023-12-06T13:54:49.133Z"

        }

        }

        }

        ],

        "links": {

        "current": "https://useast.api.elasticpath.com/v2/promotions/ad386702-e780-42c6-b190-0527ad768917/jobs?page[offset]=0&page[limit]=25",

        "first": "https://useast.api.elasticpath.com/v2/promotions/ad386702-e780-42c6-b190-0527ad768917/jobs?page[offset]=0&page[limit]=25",

        "last": "https://useast.api.elasticpath.com/v2/promotions/ad386702-e780-42c6-b190-0527ad768917/jobs?page[offset]=0&page[limit]=25",

        "prev": "https://useast.api.elasticpath.com/v2/promotions/ad386702-e780-42c6-b190-0527ad768917/jobs?page[offset]=0&page[limit]=25",

        "next": "https://useast.api.elasticpath.com/v2/promotions/ad386702-e780-42c6-b190-0527ad768917/jobs?page[offset]=0&page[limit]=25"

        },

        "meta": {

        "page": {

        "limit": 25,

        "offset": 0,

        "current": 1,

        "total": 1

        },

        "results": {

        "total": 1

        }

        }

        }

        ```'
      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: []
      operationId: getV2PromotionsByPromotionIDJobs
      x-operation-id-source: derived
    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: []
      operationId: postV2PromotionsByPromotionIDJobs
      x-operation-id-source: derived
  /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: []
      operationId: postV2PromotionsByPromotionIDJobsByJobIDCancel
      x-operation-id-source: derived
  /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: []
      operationId: getV2PromotionsByPromotionIDJobsByJobIDFile
      x-operation-id-source: derived
components:
  responses:
    PromotionCodeExportedFileResponse:
      description: Successful response
      content:
        application/json:
          schema:
            type: object
            properties:
              href:
                type: string
                description: URL to download the CSV file.
    PromotionJobsListResponse:
      description: Successful response
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/PromotionJob'
    PromotionJobCreatedResponse:
      description: Promotion job created
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                $ref: '#/components/schemas/PromotionJob'
    PromotionJobCanceledResponse:
      description: Job canceled successfully
      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
  parameters:
    Authorization:
      name: Authorization
      in: header
      description: The Bearer token required to get access to the API.
      required: true
      schema:
        type: string
        format: Bearer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer