Elastic Path Rule Promotions API
The Rule Promotions API from Elastic Path — 2 operation(s) for rule promotions.
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 Promotions 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 Promotions
paths:
/v2/rule-promotions:
post:
tags:
- Rule Promotions
summary: Create a Rule Promotion
description: "Creates a new rule-based promotion, allowing flexible discount strategies based on cart or item conditions. \nPromotions can apply fixed or percentage-based discounts, apply automatically or via codes, and have eligibility rules \nbased on product attributes, cart total, SKU conditions, custom attributes, and more.\n\nThis endpoint supports a variety of promotion types, such as:\n- **Cart-wide discounts**\n- **Item-specific discounts**\n- **Shipping discounts**\n- **Combinations thereof**\n\n:::note\n\nThe minimum item discount amount is zero, both for amounts and percentages.\n\nA store can have a maximum of **50 active and future automatic rule promotions**.\n\n:::\n"
operationId: createRulePromotion
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/Authorization'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RulePromotionItem'
examples:
CartPercentDiscount:
summary: Create a Cart Percent Discount Promotion based on cart total value
value:
data:
type: rule_promotion
name: Cart 20% discount when total is at least $100
description: 20% discount applying to the cart total
enabled: false
automatic: false
start: '2024-01-01'
end: '2025-01-01'
rule_set:
rules:
strategy: cart_total
operator: gte
args:
- 10000
actions:
- strategy: cart_discount
args:
- percent
- 20
BXGYPromotion:
summary: Create a BXGY Promotion. Buy an item and get the other item with discount.
value:
data:
type: rule_promotion
name: Buy X get Y 50%
description: Buy item SKU-X Get item SKU-Y 50% off.
enabled: true
automatic: true
start: '2024-02-01'
end: '2024-02-27'
rule_set:
rules:
strategy: item_sku
operator: in
args:
- SKU-X
actions:
- strategy: item_discount
args:
- percent
- 50
condition:
- strategy: item_sku
operator: in
args:
- SKU-Y
ItemPercentWithProductAttribute:
summary: Create an Item Percent Discount with Product Attribute
value:
data:
type: rule_promotion
name: 20% off items with attribute brand EP
description: All items with attribute brand EP get 20% discount.
enabled: true
automatic: true
start: '2024-02-01'
end: '2050-01-01'
rule_set:
rules:
strategy: item_attribute
operator: in
args:
- products(product_template)
- brand
- string
- EP
actions:
- strategy: item_discount
args:
- percent
- 20
MixedCartAndItemDiscount:
summary: Create a Mix of Cart and Item Percent Discount Promotions. Applying multiple discounts to the eligible cart.
value:
data:
type: rule_promotion
name: Buy sku1 and get cart 20% off and item sku1 50%
description: Buy sku1 get cart 20% off plus item discount 50%.
enabled: true
automatic: true
start: '2024-02-01'
end: '2024-02-10'
rule_set:
rules:
- strategy: item_sku
operator: in
args:
- sku1
actions:
- strategy: item_discount
args:
- percent
- 50
condition:
- strategy: item_sku
operator: in
args:
- sku1
- strategy: cart_discount
args:
- percent
- 20
FixedItemDiscount:
summary: Create an Item Fixed Discount Promotion
value:
data:
type: rule_promotion
name: Buy item get $10 off
description: Eligible item gets a fixed discount value of $10.
enabled: true
automatic: true
start: '2024-02-10'
end: '2024-02-22'
rule_set:
rules:
strategy: item_sku
operator: in
args:
- sku1
actions:
- strategy: item_discount
args:
- fixed
- 1000
FixedPriceItemDiscount:
summary: Create an Item Fixed Price Discount Promotion. Item price is discounted at a fixed quantity and amount.
value:
data:
type: rule_promotion
name: Buy 2 items for $100
description: 2 sku1 for $100
enabled: true
automatic: true
start: '2024-02-01'
end: '2050-01-01'
rule_set:
rules:
strategy: item_sku
operator: in
args:
- sku1
actions:
- strategy: item_discount
args:
- fixed_price
- 2
- 10000
FixedDiscountWithCatalogAndCurrencyConditions:
summary: Create a Cart Fixed Discount Promotion for a Specified Catalog and Currencies.
value:
data:
type: rule_promotion
name: $5 off cart when cart is $100 or more
description: Cart items from specific catalog with CAD or USD currency can get discount.
enabled: true
automatic: true
start: '2023-12-01'
end: '2024-01-01'
rule_set:
catalog_ids:
- 09b9359f-897f-407f-89a2-702e167fe781
currencies:
- CAD
- USD
rules:
strategy: cart_total
operator: gte
args:
- 10000
actions:
- strategy: cart_discount
args:
- fixed
- 500
CartCustomAttributePromotion:
summary: Create a Cart Percent Discount for any cart with custom attribute can get discount.
value:
data:
type: rule_promotion
name: 50 percent off cart with custom attribute
description: Cart with specific custom attribute can get discount.
enabled: true
automatic: true
start: '2024-01-01'
end: '2024-01-26'
rule_set:
rules:
strategy: cart_custom_attribute
operator: in
args:
- member_status
- string
- gold
- platinum
actions:
- strategy: cart_discount
args:
- percent
- 50
CartCustomAttributeEqualPromotion:
summary: Create a Cart Discount for carts where a custom attribute equals a specific value.
value:
data:
type: rule_promotion
name: VIP customer discount
description: 15 percent off for VIP customers
enabled: true
automatic: true
start: '2025-01-01'
end: '2030-12-31'
rule_set:
rules:
strategy: cart_custom_attribute
operator: eq
args:
- is_vip
- boolean
- true
actions:
- strategy: cart_discount
args:
- percent
- 15
CartCustomAttributeGreaterThanPromotion:
summary: Create a Cart Discount for carts where a custom attribute is greater than a value.
value:
data:
type: rule_promotion
name: Loyal customer reward
description: $5 off for customers with more than 5 previous checkouts
enabled: true
automatic: true
start: '2025-01-01'
end: '2030-12-31'
rule_set:
rules:
strategy: cart_custom_attribute
operator: gt
args:
- checkout_count
- integer
- 5
actions:
- strategy: cart_discount
args:
- fixed
- 500
CartCustomAttributeLessThanOrEqualPromotion:
summary: Create a Cart Discount for carts where a custom attribute is less than or equal to a value.
value:
data:
type: rule_promotion
name: New customer discount
description: 20 percent off for customers with 3 or fewer checkouts
enabled: true
automatic: true
start: '2025-01-01'
end: '2030-12-31'
rule_set:
rules:
strategy: cart_custom_attribute
operator: lte
args:
- checkout_count
- integer
- 3
actions:
- strategy: cart_discount
args:
- percent
- 20
CartCustomAttributeFloatComparisonPromotion:
summary: Create a Cart Discount for carts where a float custom attribute exceeds a threshold.
value:
data:
type: rule_promotion
name: High loyalty score bonus
description: 25 percent off for customers with loyalty score above 75.5
enabled: true
automatic: true
start: '2025-01-01'
end: '2030-12-31'
rule_set:
rules:
strategy: cart_custom_attribute
operator: gt
args:
- loyalty_score
- float
- 75.5
actions:
- strategy: cart_discount
args:
- percent
- 25
CartPercentDiscountExcludingItem:
summary: Create a Cart Percent Discount Excluding Specific Item.
value:
data:
type: rule_promotion
name: 50 percent off cart excluding excluded item
description: 50 percent off your order excluding excluded item
enabled: true
automatic: true
start: '2024-02-01'
end: '2050-01-01'
rule_set:
rules:
strategy: cart_total
operator: gte
args:
- 10000
children:
- strategy: item_sku
operator: nin
args:
- excludedItemSku
actions:
- strategy: cart_discount
args:
- percent
- 50
condition:
strategy: item_sku
operator: nin
args:
- excludedItemSku
ItemDiscountWithLimitations:
summary: Create Item Discount Promotion with Max Quantity Limitation.
value:
data:
type: rule_promotion
name: Buy a shirt and get max of one hat for free
description: Buy a shirt and get max of 1 hat free
enabled: true
automatic: true
start: '2024-02-01'
end: '2050-01-01'
rule_set:
rules:
strategy: item_sku
operator: in
args:
- shirt-sku
actions:
- strategy: item_discount
args:
- percent
- 100
limitations:
max_quantity: 1
condition:
- strategy: item_sku
operator: in
args:
- hat-sku
ItemDiscountWithSkuOrId:
summary: Create an Item Percent Discount targeting SKU or Product ID.
value:
data:
type: rule_promotion
name: Buy an item with SKU or Product ID get item 20% discount
description: Buy sku1 or item with productID get 20% discount
enabled: true
automatic: false
start: '2025-02-01'
end: '2050-01-01'
rule_set:
rules:
strategy: item_identifier
operator: in
args:
- skus:
- sku1
ids:
- 44d8077f-8fa3-4780-9df5-91d052be583f
actions:
- strategy: item_discount
args:
- percent
- 20
condition:
strategy: item_identifier
operator: in
args:
- skus:
- sku1
ids:
- 44d8077f-8fa3-4780-9df5-91d052be583f
ItemDiscountExcludingSkuOrId:
summary: Create an item discount excluding SKU or Product ID
value:
data:
type: rule_promotion
name: Get discount from category excluding sku or id
description: Promotion excluding items with SKU or Product ID.
enabled: true
automatic: false
start: '2025-02-01'
end: '2050-01-01'
rule_set:
rules:
strategy: item_category
operator: in
args:
- 667d9fae-d8c7-4941-b556-70cb4b8612f1
children:
- strategy: item_identifier
operator: nin
args:
- skus:
- nike_running1
ids:
- 44d8077f-8fa3-4780-9df5-91d052be583f
actions:
- strategy: item_discount
args:
- percent
- 50
condition:
strategy: item_category
operator: in
args:
- 667d9fae-d8c7-4941-b556-70cb4b8612f1
children:
- strategy: item_identifier
operator: nin
args:
- skus:
- nike_running1
ids:
- 44d8077f-8fa3-4780-9df5-91d052be583f
ItemDiscountWithRuleAndActionSubConditions:
summary: Create Item Promotion with category and attribute subconditions
value:
data:
type: rule_promotion
name: Items discount for a category excluding items with sale attribute
description: 50% item discount excluding items with attribute when eligible items exceed $100.
enabled: true
automatic: true
start: '2024-02-01'
end: '2050-01-01'
rule_set:
rules:
strategy: cart_total
operator: gte
args:
- 10000
children:
- strategy: item_category
operator: in
args:
- category-id-1
- strategy: item_attribute
operator: nin
args:
- products(product_template)
- sales
- string
- sale2024
actions:
- strategy: item_discount
args:
- percent
- 50
condition:
strategy: item_category
operator: in
args:
- category-id-1
children:
- strategy: item_attribute
operator: nin
args:
- products(product_template)
- sales
- string
- sale2024
CategoryItemDiscountWithLimitations:
summary: Create Item Promotion targeting a category excluding some items from discount
value:
data:
type: rule_promotion
name: 50% max $10 max 2 items 2 quantities from category
description: Items from category 50% off max $10 off 2 cheapest items with max quantity of 2 excluding one item.
enabled: true
automatic: true
start: '2024-02-01'
end: '2050-01-01'
rule_set:
rules:
strategy: and
children:
- strategy: item_category
operator: in
args:
- e3807d4d-010e-494c-8227-9a5cfd8f1177
- strategy: item_sku
operator: nin
args:
- exclude_item_sku
actions:
- strategy: item_discount
args:
- percent
- 50
limitations:
max_quantity: 2
max_discount: 1000
items:
max_items: 2
price_strategy: cheapest
FreeShippingForCartOver100:
summary: Create a Free Shipping Promotion
value:
data:
type: rule_promotion
name: Free FedEx Ground shipping when cart is $100 or more
description: Free FedEx Ground shipping when cart is $100 or more.
enabled: true
automatic: false
start: '2024-08-01'
end: '2050-12-31'
rule_set:
rules:
strategy: cart_total
operator: gte
args:
- 10000
actions:
- strategy: shipping_discount
args:
- percent
- 100
condition:
strategy: shipping_type
operator: in
args:
- fedex_ground
ItemsBundleDiscount:
summary: Create a Bundle Promotion for specific item skus with specific quantity requirement
value:
data:
type: rule_promotion
name: Buy 2 tennis rackets and 3 tennis balls, get fixed price bundle discount
description: Bundle items targeting specific item skus and quantity values.
enabled: true
automatic: false
start: '2025-02-01'
end: '2025-03-31'
rule_set:
rules:
strategy: items_bundle
children:
- strategy: and
children:
- strategy: item_sku
operator: in
args:
- tennis_racket
- strategy: item_quantity
operator: eq
args:
- 2
- strategy: and
children:
- strategy: item_sku
operator: in
args:
- tennis_balls
- strategy: item_quantity
operator: eq
args:
- 3
actions:
- strategy: items_bundle_discount
args:
- fixed_price
- 20000
condition:
strategy: items_bundle
children:
- strategy: and
children:
- strategy: item_sku
operator: in
args:
- tennis_racket
- strategy: item_quantity
operator: eq
args:
- 2
- strategy: and
children:
- strategy: item_sku
operator: in
args:
- tennis_balls
- strategy: item_quantity
operator: eq
args:
- 3
ItemsBundleWithSingleCondition:
summary: Create a Bundle Promotion with single condition. Bundle items can be selected from a single category with a required minimum quantity. This can be either a single item meeting the quantity requirement or multiple items whose combined quantity satisfies the requirement.
value:
data:
type: rule_promotion
name: Buy any 2 or more items from shoes category, get 50% off
description: Buy any 2 shoes get 50% off.
enabled: true
automatic: false
start: '2025-05-01'
end: '2025-05-31'
rule_set:
rules:
strategy: items_bundle
children:
- strategy: and
children:
- strategy: item_category
operator: in
args:
- 667d9fae-d8c7-4941-b556-70cb4b8612f1
- strategy: item_quantity
operator: eq
args:
- 2
actions:
- strategy: items_bundle_discount
args:
- percent
- 50
condition:
strategy: items_bundle
children:
- strategy: and
children:
- strategy: item_category
operator: in
args:
- 667d9fae-d8c7-4941-b556-70cb4b8612f1
- strategy: item_quantity
operator: eq
args:
- 2
BundleWithMixedItemsAcrossCategories:
summary: Create a Bundle Promotion with mixed category and item quantity requirements. A bundle promotion that requires items from two categories, allowing the total quantity to be fulfilled by a mix of eligible items.
value:
data:
type: rule_promotion
name: Buy 2 items each from the "Shoes" and "Socks" categories to get a 50% bundle discount
description: Buy 2 items from shoes and socks to get 50% bundle discount.
enabled: true
automatic: false
start: '2025-05-01'
end: '2025-05-31'
rule_set:
rules:
strategy: items_bundle
children:
- strategy: and
children:
- strategy: item_category
operator: in
args:
- 667d9fae-d8c7-4941-b556-70cb4b8612f1
- strategy: item_quantity
operator: eq
args:
- 2
- strategy: and
children:
- strategy: item_category
operator: in
args:
- 7700645a-55bd-4159-a8f3-ade7fed387c4
- strategy: item_quantity
operator: eq
args:
- 2
actions:
- strategy: items_bundle_discount
args:
- percent
- 50
condition:
strategy: items_bundle
children:
- strategy: and
children:
- strategy: item_category
operator: in
args:
- 667d9fae-d8c7-4941-b556-70cb4b8612f1
- strategy: item_quantity
operator: eq
args:
- 2
- strategy: and
children:
- strategy: item_category
operator: in
args:
- 7700645a-55bd-4159-a8f3-ade7fed387c4
- strategy: item_quantity
operator: eq
args:
- 2
AccountTagsPromotion:
summary: Create a Cart Percent Discount with Account Tags Rule Promotion. Account must contain all account tags to be eligible for the discount.
value:
data:
type: rule_promotion
name: 50 percent off cart with account tags
description: Account contains all matching account tags get 50 percent cart discount
enabled: true
automatic: true
start: '2025-06-01'
end: '2026-06-30'
rule_set:
rul
# --- truncated at 32 KB (102 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/openapi/elastic-path-rule-promotions-api-openapi.yml