Elastic Path Rule Promotion Codes API
The Rule Promotion Codes API from Elastic Path — 2 operation(s) for rule promotion codes.
OpenAPI Specification
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 Rule Promotion Codes 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: Rule Promotion Codes
paths:
/v2/rule-promotions/{promotionID}/codes:
post:
tags:
- Rule Promotion Codes
summary: Create Rule Promotion Codes
description: "Creates new promotion codes for a specific rule promotion, allowing customers to redeem discounts based on predefined conditions.\n\n- Supports bulk creation of multiple promotion codes in a single request.\n- Each code can have individual usage limits.\n- Can optionally assign codes to specific users to enforce targeted promotions.\n- The promotion codes are case-insensitive.\n\n:::note\n\nRegarding first time shopper limitations:\n- Orders without payment transactions do not count as completed purchases.\n- Canceling or refunding an order does not reinstate first-time shopper status.\n- A first-time shopper coupon code cannot have limited uses or be assigned to specific users, meaning the code cannot be restricted by the number of times it can be used or tied to a specific customer ID.\n\n:::\n\nA successful request returns a `201 Created` response with details of the generated promotion codes.\n\n### Duplicate Codes\nDuplicate promotion codes **are supported across different promotions** in the store, regardless of their statuses and validity dates. However, **duplicate codes cannot be created within the same promotion**.\nThis means that shoppers can apply a single coupon code to trigger multiple promotions if those promotions share common coupon codes. \n\nCodes that share the same name can serve different purposes. For example, one code may have `per_application` with a limited number of uses, while another identical code can have `per_checkout` with unlimited use.\n\n**Duplicate Code Handling:**\n- If a duplicate code is detected **within the same promotion**, the request will return a `422 Duplicate code` error.\n- When creating duplicate codes, a message appears with the successful response indicating the duplication.\n\n\nPlease refer to the **OpenAPI examples** section on this page for sample request structures.\n"
operationId: createRulePromotionCodes
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/Authorization'
- name: promotionID
in: path
required: true
schema:
type: string
description: The unique identifier of the rule promotion.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PromotionCodesRequest'
examples:
CreateCodes:
summary: Create Rule Promotion Codes
value:
data:
type: promotion_codes
codes:
- code: spring2024
- code: summer2024
consume_unit: per_checkout
- code: summer2024_limited
consume_unit: per_application
uses: 5
- code: summer2024_memberOnly
consume_unit: per_application
uses: 1
user: vip_shopper@email.com
SingleUsePerShopperIncludingGuests:
summary: Create a Promotion Code Usable Once Per Shopper, Including Guest Shoppers with Emails Associated with their Carts
value:
data:
type: promotion_codes
codes:
- code: one_per_shopper
consume_unit: per_checkout
max_uses_per_shopper:
includes_guests: true
max_uses: 1
MaxUsesLimitWithPerShopperRestriction:
summary: Create a Promotion Code with a Total Usage Limit and Per Shopper Restriction
description: 'Create a promotion code that allows up to **10 total uses** and allows each individual shopper to use the code **once**.
- The `uses` field is set to `10`, meaning the promotion code can be redeemed a maximum of **10 times across all shoppers**.
- The `max_uses_per_shopper` field sets `max_uses: 1`, ensuring **each shopper can only redeem the code once**.
- The `includes_guests` field is set to `true`, allowing **both registered and guest shoppers** to use the promotion code.
- The `consume_unit` is set to `per_checkout`, meaning the code is **consumed once per successful checkout**.
This setup is useful for **one-time promotions** where a **limited number of shoppers can redeem the code** but prevents any single shopper from claiming multiple redemptions.
'
value:
data:
type: promotion_codes
codes:
- code: one_time_use
consume_unit: per_checkout
uses: 10
max_uses_per_shopper:
includes_guests: true
max_uses: 1
MaxUsesForSpecificShopper:
summary: Limit Promotion Code Usage to a Specific Shopper
description: 'Create a promotion which **limits the maximum usage of a promotion code to a specific shopper** based on their `customerID`.
- The `uses` field is set to `1`, meaning **this promotion code can only be used once by the identified shopper**.
- The `user` field is set to `customer-id-123`, ensuring the **code is only valid when the cart is checked out by the specified customer**.
- The `consume_unit` is set to `per_checkout`, meaning the code is **redeemed upon a successful checkout**.
**Important Notes:**
- This method is useful for **targeted, personalized promotions** where only a specific shopper should receive the discount.
- The promotion code **cannot be used by any other shopper**.
- **Account user IDs are currently not supported**.
This setup is ideal for **single-use, customer-specific promotions**, such as loyalty rewards or personalized discount offers.
'
value:
data:
type: promotion_codes
codes:
- code: one_per_shopper
consume_unit: per_checkout
uses: 1
user: customer-id-123
MaxUsesForSpecificRegisteredShopper:
summary: Limit Promotion Code Usage to a Specific Registered Shopper
description: 'This example demonstrates how to **restrict a promotion code to a specific registered shopper** using their `customerID`, with a limit on how many times they can redeem the code.
- The `user` field is set to `customer-id-123`, ensuring **only the specified shopper can use the promotion code**.
- The `max_uses_per_shopper.max_uses` field is set to `1`, meaning **this shopper can only redeem the code once**.
- The `max_uses_per_shopper.includes_guests` field is set to `false`, meaning **guest shoppers cannot use this code**.
- The `consume_unit` is set to `per_checkout`, meaning **the code is consumed once per successful checkout**.
**Key Differences from Other Shopper-Specific Limits:**
- Unlike a `uses: 1` setup, which sets a global limit for the code, this method **explicitly enforces per-shopper usage limits**.
- This approach is ideal for **exclusive promotions targeting specific registered shoppers**, ensuring that only they can redeem the discount and preventing usage by guest shoppers.
- **Account user IDs are currently not supported**.
This setup is useful for **member-only discounts, personalized promotional offers, or exclusive VIP rewards**.
'
value:
data:
type: promotion_codes
codes:
- code: one_per_shopper
consume_unit: per_checkout
user: customer-id-123
max_uses_per_shopper:
includes_guests: false
max_uses: 1
FirstTimeShopperCodeRequest:
summary: Create a Promotion Code for First-Time Shoppers
description: 'Create a **promotion code that is only applicable to first-time shoppers**. Here, the `is_for_new_shopper` field is set to `true`, indicating that **only first-time shoppers can use this code**.
**Important Notes:**
- Promotion codes with `is_for_new_shopper: true` **cannot have usage limits** (`uses`) or be assigned to specific users.
- If usage limits or shopper assignments are included, a **400 Invalid Code error** will be returned.
'
value:
data:
type: promotion_codes
codes:
- code: first_time
is_for_new_shopper: true
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePromotionCodesResponse'
examples:
PromotionCodeCreatedResponse:
summary: Response When a Promotion Code is Successfully Created
value:
data:
- id: 8a1c73bc-7c15-41c3-a3ed-a0aa398c3984
code: one_per_shopper
user: 5abb8d4e-57c0-459b-91d5-c4e6f77e9c5e
max_uses_per_shopper:
max_uses: 1
includes_guests: false
consume_unit: per_checkout
FullyConsumedPromotionCodeResponse:
summary: Response When a Promotion Code Has Been Fully Used
description: 'Response indicating that a **promotion code has already been fully consumed** by the shopper and is no longer valid for use.
- The `source.id` field provides the unique identifier of the promotion.
- The `source.code` field specifies the exact promotion code that has been fully consumed.
- The `title` field (`"Fully Consumed"`) serves as a user-friendly summary of the issue.
- The `description` field provides a clear explanation: `"You''ve already fully consumed this promotion code"`.
This response is useful for handling **errors when applying promotion codes**, ensuring that customers receive **clear feedback** if they attempt to reuse a code that has reached its usage limit.
'
value:
messages:
- source:
type: promotion_codes
id: 38861a5c-81bb-43bc-8934-e30cde108579
code: one_per_shopper
title: Fully Consumed
description: You've already fully consumed this promotion code
DuplicateCodeNameResponse:
summary: Message Response When Creating a Duplicate Promotion Code Name
value:
messages:
- source:
type: promotion_codes
codes:
- duplicate-code
title: Duplicate code names
description: Code names duplicated in other promotions
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
status:
type: integer
example: 400
source:
type: string
example: data.codes.0.max_uses_per_shopper
title:
type: string
example: missing_dependency
detail:
type: string
example: Has a dependency on max_uses
examples:
MissingMaxUsesDependencyError:
summary: Error When `max_uses_per_shopper.includes_guests` is Provided Without `max_uses`
description: 'This error occurs when `max_uses_per_shopper.includes_guests` is provided **without specifying** `max_uses`.
'
value:
errors:
- status: 400
source: data.codes.0.max_uses_per_shopper
title: missing_dependency
detail: Has a dependency on max_uses
FirstTimeShopperCodeError:
summary: Error When Setting Usage Limits While Assigning First-Time Shopper Codes
description: 'This error occurs when a **first-time shopper promotion code** is created **with restricted uses (`uses`) or assigned to specific users (`user`)**.
'
value:
errors:
- status: 400
source: ''
title: Invalid Code
detail: Code - first_time_uses can't have limited uses or assigned to users since it's for first-time shoppers.
'422':
description: Unprocessable Entity
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
status:
type: string
example: '422'
source:
type: string
example: ''
title:
type: string
example: Unsupported consume unit
detail:
type: string
example: Consume unit 'per_application' is not supported when using 'max_uses_per_shopper' features.
examples:
UnsupportedConsumeUnitError:
summary: Error When `max_uses_per_shopper.max_uses` is Used with `per_application`
description: 'This error occurs when `max_uses_per_shopper.max_uses` is set while using `consume_unit: per_application`, which is not supported.
'
value:
errors:
- status: '422'
source: ''
title: Unsupported consume unit
detail: Consume unit 'per_application' is not supported when using 'max_uses_per_shopper' features.
NoCodesAllowedForAutomaticPromotion:
summary: Error When Attempting to Create Promotion Codes for Automatic Promotions
value:
errors:
- status: '422'
title: No codes allowed
detail: Cannot add codes to automatic promotion
DuplicatePromotionCodeError:
summary: Error When Creating a Promotion Code That Already Exists
description: 'This error occurs when attempting to create a promotion code that already exists within the same Rule Promotion.
'
value:
errors:
- status: '422'
title: Duplicate code
detail: Promotion code already in use
get:
tags:
- Rule Promotion Codes
summary: Get Rule Promotion Codes
description: 'Retrieves the list of promotion codes associated with a specific Rule Promotion.
- Returns all codes generated for the given promotion ID, including details on usage limits and redemption status.
- Supports both automatically generated and manually created promotion codes.
- Can be used to verify whether a promotion code is still valid or has reached its usage limit.
'
operationId: getRulePromotionCodes
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/Authorization'
- name: promotionID
in: path
required: true
schema:
type: string
description: The unique identifier of the rule promotion.
- name: filter
in: query
schema:
type: string
description: 'This parameter accepts a filtering expression that uses specific operators and attributes. Promotion codes are case-insensitive.
The following operators and attributes are available when filtering on this endpoint. See [Supported Filtering Characters](/guides/Getting-Started/filtering#supported-characters).
| Attribute | Type | Operator | Example |
|:--------- |:---------|:------------|:---------------|
| `code` | `string`, `number` | `eq`, `gt` | `eq(code,summer2024)`, `gt(code,2024)` |
'
- name: sort
in: query
schema:
type: string
enum:
- code
- -code
x-enumDescriptions:
code: Sort in increasing order of code, case-insensitively.
-code: Sort in decreasing order of code, case-insensitively.
description: 'Specifies the order of the codes that will be returned.
'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetPromotionCodesResponse'
delete:
tags:
- Rule Promotion Codes
summary: Delete Rule Promotion Codes
description: 'Deletes one or more promotion codes from a specific rule promotion.
- Supports **bulk deletion**, allowing multiple codes to be removed in a single request.
- Removes promotion codes permanently, making them unavailable for future use.
- If a code has already been redeemed, it will be removed from the system but may still reflect in historical transactions.
A successful request returns a `204 No Content` response, indicating the specified promotion codes have been deleted.
'
operationId: deleteRulePromotionCodes
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/Authorization'
- name: promotionID
in: path
required: true
schema:
type: string
description: The unique identifier of the rule promotion.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PromotionCodesRequest'
examples:
DeleteCodes:
summary: Delete Rule Promotion Codes
value:
data:
type: promotion_codes
codes:
- code: spring2024
- code: summer2024
consume_unit: per_checkout
- code: summer2024_limited
consume_unit: per_application
uses: 5
- code: summer2024_memberOnly
consume_unit: per_application
uses: 1
user: vip_shopper@email.com
responses:
'204':
description: No Content
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Response.Error'
/v2/rule-promotions/{promotionID}/codes/{codeID}:
delete:
tags:
- Rule Promotion Codes
summary: Delete A Single Rule Promotion Code
description: 'Deletes a single promotion code from a specific rule promotion.
- Permanently removes the specified promotion code, making it unavailable for future use.
- Can be used to **revoke a specific code** without affecting other codes under the same promotion.
- If the code has already been redeemed, it will still be removed from the system but may still reflect in historical transactions.
A successful request returns a `204 No Content` response, indicating the specified promotion code has been deleted.
'
operationId: deleteSingleRulePromotionCode
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/Authorization'
- name: promotionID
in: path
required: true
schema:
type: string
description: The unique identifier of the rule promotion.
- name: codeID
in: path
required: true
schema:
type: string
description: The unique identifier of the rule promotion code.
responses:
'204':
description: No Content
components:
schemas:
CreatePromotionCodeResponse:
type: object
properties:
id:
type: string
format: uuid
type:
type: string
const: promotion_codes
code:
type: string
uses:
type: integer
user:
type: string
consume_unit:
type: string
enum:
- per_application
- per_checkout
max_uses:
type: integer
max_uses_per_shopper:
$ref: '#/components/schemas/MaxUsesPerShopper'
is_for_new_shopper:
type: boolean
MaxUsesPerShopper:
type: object
description: Object for setting max uses per shopper. Only include this object, when you want to set limit per shopper.
properties:
max_uses:
type: integer
description: Sets max number of times the code can be used by a shopper. NOTE - This cannot be set with `per_application` consume unit.
includes_guests:
type: boolean
default: false
description: The flag to include guest shoppers for the discount with max use restriction. **If this field is provided, the max_uses value is required.** When set to `true`, guest shoppers must have an email associated with the cart to use the code. A guest cart without an email cannot use the code. When set to `false`, guest shoppers cannot use the promo code, even if the cart has an associated guest email.
GetPromotionCodesResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/GetPromotionCodeResponse'
links:
$ref: '#/components/schemas/PaginationLinks'
meta:
$ref: '#/components/schemas/PaginationMeta'
CreatePromotionCodesResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/CreatePromotionCodeResponse'
messages:
type: array
items:
$ref: '#/components/schemas/PromotionCodeMessage'
PaginationMeta:
type: object
properties:
page:
type: object
properties:
current:
type: integer
description: Current page number
limit:
type: integer
description: Number of items per page
offset:
type: integer
description: Offset from the first result
total:
type: integer
description: Total number of pages
results:
type: object
properties:
total:
type: integer
description: Total number of results
total_method:
type: string
description: Method used to calculate the total (e.g., 'exact')
PaginationLinks:
type: object
properties:
current:
type: string
format: uri
description: URL for the current page of results
first:
type: string
format: uri
description: URL for the first page of results
last:
type: string
format: uri
description: URL for the last page of results
next:
type: string
format: uri
description: URL for the next page of results
prev:
type: string
format: uri
description: URL for the previous page of results
PromotionCodesRequest:
type: object
properties:
data:
type: object
properties:
type:
type: string
const: promotion_codes
codes:
type: array
description: Specifies the code details in an array of objects.
items:
type: object
properties:
code:
type: string
description: Specifies the string to use as a code for the promotion.
uses:
type: integer
description: Specifies the number of times the code can be used. If no value is set, the customer can use the code any number of times.
user:
type: string
description: Specifies the customer ID of the shopper who can use the code. For more information, see the [Create a customer](/docs/customer-management/customer-management-api/create-a-customer) section.
consume_unit:
type: string
enum:
- per_application
- per_checkout
description: '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.
'
max_uses_per_shopper:
$ref: '#/components/schemas/MaxUsesPerShopper'
is_for_new_shopper:
type: boolean
description: A flag indicating whether the coupon is for first-time shoppers. If set to `true`, the discount will only apply if the shopper has never made a payment on any order in the store. If set to `false` or left unset, it will be a regular discount that applies to all shoppers. When this flag is set to `true`, the coupon cannot have usage limitations or be assigned to specific users.
Response.Error:
type: object
properties:
errors:
type: array
items:
type: object
properties:
status:
type:
- string
- integer
description: HTTP status code.
title:
type: string
description: Error title.
detail:
type: string
description: Error details.
source:
type: string
description: Source of the error (e.g., which field or parameter caused the error)
meta:
type: object
properties:
usage_ids:
type: array
items:
type: string
PromotionCodeMessage:
type: object
properties:
source:
type: object
description: Information about the affected promotion codes.
properties:
type:
type: string
const: promotion_codes
description: Indicates that the affected entity is a promotion code.
codes:
type: array
description: A list of promotion codes that triggered the message.
items:
type: string
example: spring2024
title:
type: string
description: A brief title summarizing the message.
example: Duplicate code names
description:
type: string
description: A detailed explanation of the message.
example: Code names duplicated in other promotions
GetPromotionCodeResponse:
type: object
properties:
type:
type: string
const: promotion_codes
id:
type: string
format: uuid
description: Unique identifier for the promotion code
code:
type: string
uses:
type: integer
user:
type: string
consume_unit:
type: string
enum:
- per_application
- per_checkout
description: '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.
'
max_uses:
type: integer
max_uses_per_shopper:
$ref: '#/components/schemas/MaxUsesPerShopper'
is_for_new_shopper:
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/openapi/elastic-path-rule-promotion-codes-api-openapi.yml