List and manage promotions and apply them at checkout - submit a cart to retrieve applicable promotions and finalize the checkout with the resulting discounts.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/antavo-promotion-engine-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.0.0
info:
contact: {}
title: Antavo Promotion Engine API
version: 1.0.0
servers:
- url: https://promotion.test.antavo.com/api
description: The Promotion Engine test environtment
paths:
/v1/promotion/{promotionId}:
get:
tags:
- Promotion
summary: Retrieve a specific promotion by ID
description: The endpoint provides detailed information about a specific promotion.
security:
- bearerAuth: []
parameters:
- in: path
name: promotionId
schema:
type: string
required: true
description: Unique indentifier of the promotion.
example: 01JW4M2FS0CX9DQETDV142JB4M
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
description: Indicates the success of the request. Always `success` here.
metadata:
type: object
description: Reserved for future use; currently returns an empty object.
payload:
$ref: '#/components/schemas/promotionModel'
description: Details of the promotion object.
examples:
bonusProducts:
summary: Bonus product promotion
value:
id: 01JVYEHFT9559EHVCMF3WPNNER
workspaceId: '500'
name: Denim 3+1
status: archived
description: Denim 3+1
type: bonusProducts
imageURL: https://antavo.com
priority: 1
currency: EUR
stackingConfiguration:
selfStackingConfiguration:
isAllowed: true
limit: 2
stackingType: exclusive
excludedPromotionIds: null
applicationsResetSchedule: null
restriction:
timeRestriction:
start: 2025-05-01 13:29
end: 2025-05-10 13:29
recurringSchedule: null
applicationsCountLimit: 0
minTotalBeforeTax: '10'
maxTotalBeforeTax: '14'
storeRestriction:
stores:
- 5077595177C60923
storeGroups:
- Germany
- Austria
bonusProducts:
products: []
categories:
- categoryId: Apparel & Accessories > Clothing > Pants
quantity: 3
itemMatchingRule: any
discount:
bonusProducts:
products:
- productId: '2235462'
quantity: 1
value: '50.00'
priceReduction:
summary: Price reduction promotion
value:
id: 01JW462QYYXJVFTMT91BPXTBBQ
workspaceId: '500'
name: €10 OFF on Skirts
status: active
description: €10 OFF on Skirts
type: priceReduction
imageURL: https://antavo.com
priority: 1
currency: EUR
stackingConfiguration:
selfStackingConfiguration:
isAllowed: false
limit: 0
stackingType: selectiveStackable
excludedPromotionIds:
- 01JVYEHFT9559EHVCMF3WPNNER
applicationsResetSchedule: null
restriction:
timeRestriction:
start: 2025-05-18 18:56
end: 2025-05-24 00:00
recurringSchedule: FREQ=DAILY;DTSTART=20250518T185600;DTEND=20250524T185600;INTERVAL=4
applicationsCountLimit: 0
minTotalBeforeTax: '10'
maxTotalBeforeTax: ''
storeRestriction:
stores:
- 5077595177C60923
storeGroups:
- Austria
priceReduction:
productIds: []
categoryIds:
- Apparel & Accessories > Clothing > Skirts
discount:
priceReduction:
type: fixed
amount: '1.00'
promoCode:
summary: Promo code promotion
value:
id: 01JW46XJ530J9Z4Y3PKYC3MCST
workspaceId: '500'
name: Spring 15% Promotion
status: active
description: Celebrate the spring season with 15% off on each product.
type: promoCode
imageURL: https://antavo.com
priority: 1
currency: EUR
stackingConfiguration:
selfStackingConfiguration:
isAllowed: false
limit: 0
stackingType: stackable
excludedPromotionIds: null
applicationsResetSchedule: null
restriction:
timeRestriction:
start: 2025-03-01 19:10
end: 2025-05-31 22:34
recurringSchedule: FREQ=WEEKLY;DTSTART=20250301T191000;DTEND=20250531T191000;INTERVAL=1
applicationsCountLimit: 0
minTotalBeforeTax: '5'
maxTotalBeforeTax: '100'
storeRestriction:
stores: []
storeGroups:
- Austria
promoCode:
promoCode: SPRING15
excludedProducts: []
discount:
promoCode:
type: percentage
amount: '15.00'
bundle:
summary: Bundle promotion
value:
id: 01JW4K0FSPZ3GHKN5TWRKJZ5DV
workspaceId: '500'
name: Summer Skincare Bundle
status: draft
description: Curated skincare products bundle for summer glow and hydration.
type: bundle
imageURL: https://antavo.com
priority: 1
currency: EUR
stackingConfiguration:
selfStackingConfiguration:
isAllowed: false
limit: 0
stackingType: exclusive
excludedPromotionIds: null
applicationsResetSchedule: null
restriction:
timeRestriction:
start: 2025-06-01 22:37
end: 2025-08-30 22:37
recurringSchedule: null
applicationsCountLimit: 0
minTotalBeforeTax: ''
maxTotalBeforeTax: ''
storeRestriction:
stores:
- 47847307C1652044
storeGroups:
- Austria
bundle:
productIds:
- '32087'
- '89412'
- '16532'
categoryIds:
- Skincare
discount:
bundle:
type: groupPriceBeforeTax
amount: '149.99'
BuyXForTotalAmount:
summary: Buy X for total Y promotion
value:
id: 01JW4K7MJJKJB1C58F1CP3K2ZQ
workspaceId: '500'
name: Buy 4 pens total for €10.
status: active
description: Buy any 4 pens for a total price of €10.
type: buyXForTotalAmount
imageURL: https://antavo.com
priority: 1
currency: EUR
stackingConfiguration:
selfStackingConfiguration:
isAllowed: true
limit: 5
stackingType: stackable
excludedPromotionIds: null
applicationsResetSchedule: null
restriction:
timeRestriction:
start: 2025-08-01 22:45
end: 2025-09-30 22:45
recurringSchedule: null
applicationsCountLimit: 0
minTotalBeforeTax: '10'
maxTotalBeforeTax: ''
storeRestriction:
stores: []
storeGroups:
- Germany
buyXForTotalAmount:
quantity: 4
item: Stationery
itemType: category
discount:
buyXForTotalAmount:
groupPriceBeforeTax: '10.00'
itemSelectionStrategy: cheapest
buyXGet1free:
summary: Buy X get 1 free (BOGO) promotion
value:
id: 01JW4KAXA32N9ZGEERG7MHMR0X
workspaceId: '500'
name: Buy 3 get 1 free bundle
status: active
description: Buy 3 shirts, get 1 free.
type: buyXGetYFree
imageURL: https://antavo.com
priority: 1
currency: EUR
stackingConfiguration:
selfStackingConfiguration:
isAllowed: true
limit: 3
stackingType: exclusive
excludedPromotionIds: null
applicationsResetSchedule: null
restriction:
timeRestriction:
start: 2025-03-01 22:48
end: 2025-05-31 22:48
recurringSchedule: null
applicationsCountLimit: 0
minTotalBeforeTax: '20'
maxTotalBeforeTax: ''
storeRestriction:
stores:
- 5077595177C60923
- 47847307C1652044
storeGroups:
- Austria
buyXGetYFree:
quantity: 3
item: '2223640'
itemType: product
discount:
buyXGetYFree:
freeProductSelectionStrategy: cheapest
quantity: 1
crossSelling:
summary: Cross-selling promotion
value:
id: 01JW4KGCRX5V5213XT9DXZD6QS
workspaceId: '500'
name: Cross-sell winter hats
status: draft
description: Get 25% off hats when buying jackets.
type: crossSelling
imageURL: https://antavo.com
priority: 1
currency: EUR
stackingConfiguration:
selfStackingConfiguration:
isAllowed: true
limit: 0
stackingType: exclusive
excludedPromotionIds: null
applicationsResetSchedule: null
restriction:
timeRestriction:
start: 2025-12-01 22:50
end: 2025-12-06 22:50
recurringSchedule: null
applicationsCountLimit: 0
minTotalBeforeTax: '10'
maxTotalBeforeTax: ''
storeRestriction:
stores: []
storeGroups:
- Germany
crossSelling:
productIds: []
categoryIds:
- Apparel & Accessories > Clothing > Jackets
discount:
crossSelling:
categories:
- categoryId: Apparel & Accessories > Clothing > Hats
type: percentage
amount: '25.00'
products: []
itemSelectionStrategy: cheapest
freeSample:
summary: Free sample promotion
value:
id: 01JW4KR347PV2MA9943TD38YQS
workspaceId: '500'
name: Free perfume sample
status: active
description: Try a free perfume sample with any order.
type: freeSample
imageURL: https://antavo.com
priority: 1
currency: EUR
stackingConfiguration:
selfStackingConfiguration:
isAllowed: false
limit: 0
stackingType: exclusive
excludedPromotionIds: null
applicationsResetSchedule: null
restriction:
timeRestriction:
start: 2025-01-01 22:55
end: 2025-12-31 22:55
recurringSchedule: null
applicationsCountLimit: 0
minTotalBeforeTax: '100'
maxTotalBeforeTax: ''
storeRestriction:
stores: []
storeGroups:
- Germany
- Austria
freeSample:
products: []
categories:
- categoryId: Perfumes
quantity: 1
itemMatchingRule: any
discount:
freeSample:
productId: '87654'
quantity: 1
value: '0.00'
productSet:
summary: Product set promotion
value:
id: 01JW4KY3F49J3NMDF83Y7R5N7F
workspaceId: '500'
name: Winter coat and scarf set
status: draft
description: Buy coat & scarf set, get 12% off.
type: productSet
imageURL: https://antavo.com
priority: 1
currency: EUR
stackingConfiguration:
selfStackingConfiguration:
isAllowed: false
limit: 0
stackingType: selectiveStackable
excludedPromotionIds:
- 01JW4KGCRX5V5213XT9DXZD6QS
applicationsResetSchedule: null
restriction:
timeRestriction:
start: 2025-11-01 22:57
end: 2025-12-31 22:57
recurringSchedule: null
applicationsCountLimit: 0
minTotalBeforeTax: ''
maxTotalBeforeTax: ''
storeRestriction:
stores:
- 47847307C1652044
storeGroups:
- Austria
productSet:
products: []
categories:
- categoryId: Apparel & Accessories > Clothing > Coats
quantity: 1
- categoryId: Apparel & Accessories > Clothing > Scarfs
quantity: 1
discount:
productSet:
type: percentage
amount: '12.00'
itemSelectionStrategy: cheapest
promotionalPricing:
summary: Promotional pricing promotion
value:
id: 01JW4M2FS0CX9DQETDV142JB4M
workspaceId: '500'
name: Sneakers promotional price
status: active
description: Sneakers at €70 during promotion.
type: promotionalPricing
imageURL: https://antavo.com
priority: 1
currency: EUR
stackingConfiguration:
selfStackingConfiguration:
isAllowed: false
limit: 0
stackingType: stackable
excludedPromotionIds: null
applicationsResetSchedule: null
restriction:
timeRestriction:
start: 2025-07-01 23:01
end: 2025-07-31 23:01
recurringSchedule: null
applicationsCountLimit: 0
minTotalBeforeTax: ''
maxTotalBeforeTax: ''
storeRestriction:
stores: []
storeGroups:
- Austria
promotionalPricing:
productIds: []
categoryIds:
- Apparel & Accessories > Clothing > Shoes > Sneakers
discount:
promotionalPricing:
unitPriceBeforeTax: '70.00'
'403':
$ref: '#/components/responses/TokenValidationError'
'404':
$ref: '#/components/responses/ModelNotFoundError'
/v1/promotions:
get:
tags:
- Promotion
summary: Retrieve the list of promotions
description: 'Fetches all promotions [configured](https://docs.antavo.com/docs/configuring-promotions)
in your workspace. The response includes the full promotion objects with all settings as configured
in the UI. Useful for listing, syncing, or debugging active campaign setups.
No request parameters are required.
'
security:
- bearerAuth: []
responses:
'200':
description: A success response returns all configured promotions.
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: Indicates the success of the request. Always `success` here.
example: success
metadata:
type: object
description: Reserved for pagination or additional metadata.
payload:
type: array
description: List of promotion objects.
items:
$ref: '#/components/schemas/promotionModel'
examples:
allPromotionTypes:
summary: Example with all promotion types
value:
status: success
metadata: []
payload:
- id: 01JVYEHFT9559EHVCMF3WPNNER
workspaceId: '500'
name: Denim 3+1
status: archived
description: Denim 3+1
type: bonusProducts
imageURL: https://antavo.com
priority: 1
currency: EUR
stackingConfiguration:
selfStackingConfiguration:
isAllowed: true
limit: 2
stackingType: exclusive
excludedPromotionIds: null
applicationsResetSchedule: null
restriction:
timeRestriction:
start: 2025-05-01 13:29
end: 2025-05-10 13:29
recurringSchedule: null
applicationsCountLimit: 0
minTotalBeforeTax: '10'
maxTotalBeforeTax: '14'
storeRestriction:
stores:
- 5077595177C60923
storeGroups:
- Germany
- Austria
bonusProducts:
products: []
categories:
- categoryId: Apparel & Accessories > Clothing > Pants
quantity: 3
itemMatchingRule: any
discount:
bonusProducts:
products:
- productId: '2235462'
quantity: 1
value: '50.00'
- id: 01JW462QYYXJVFTMT91BPXTBBQ
workspaceId: '500'
name: €10 OFF on Skirts
status: active
description: €10 OFF on Skirts
type: priceReduction
imageURL: https://antavo.com
priority: 1
currency: EUR
stackingConfiguration:
selfStackingConfiguration:
isAllowed: false
limit: 0
stackingType: selectiveStackable
excludedPromotionIds:
- 01JVYEHFT9559EHVCMF3WPNNER
applicationsResetSchedule: null
restriction:
timeRestriction:
start: 2025-05-18 18:56
end: 2025-05-24 00:00
recurringSchedule: FREQ=DAILY;DTSTART=20250518T185600;DTEND=20250524T185600;INTERVAL=4
applicationsCountLimit: 0
minTotalBeforeTax: '10'
maxTotalBeforeTax: ''
storeRestriction:
stores:
- 5077595177C60923
storeGroups:
- Austria
priceReduction:
productIds: []
categoryIds:
- Apparel & Accessories > Clothing > Skirts
discount:
priceReduction:
type: fixed
amount: '1.00'
- id: 01JW46XJ530J9Z4Y3PKYC3MCST
workspaceId: '500'
name: Spring 15% Promotion
status: active
description: Celebrate the spring season with 15% off on each product.
type: promoCode
imageURL: https://antavo.com
priority: 1
currency: EUR
stackingConfiguration:
selfStackingConfiguration:
isAllowed: false
limit: 0
stackingType: stackable
excludedPromotionIds: null
applicationsResetSchedule: null
restriction:
timeRestriction:
start: 2025-03-01 19:10
end: 2025-05-31 22:34
recurringSchedule: FREQ=WEEKLY;DTSTART=20250301T191000;DTEND=20250531T191000;INTERVAL=1
applicationsCountLimit: 0
minTotalBeforeTax: '5'
maxTotalBeforeTax: '100'
storeRestriction:
stores: []
storeGroups:
- Austria
promoCode:
promoCode: SPRING15
excludedProducts: []
discount:
promoCode:
type: percentage
amount: '15.00'
- id: 01JW4K0FSPZ3GHKN5TWRKJZ5DV
workspaceId: '500'
name: Summer Skincare Bundle
status: draft
description: Curated skincare products bundle for summer glow and hydration.
type: bundle
imageURL: https://antavo.com
priority: 1
currency: EUR
stackingConfiguration:
selfStackingConfiguration:
isAllowed: false
limit: 0
stackingType: exclusive
excludedPromotionIds: null
applicationsResetSchedule: null
restriction:
timeRestriction:
start: 2025-06-01 22:37
end: 2025-08-30 22:37
recurringSchedule: null
applicationsCountLimit: 0
minTotalBeforeTax: ''
maxTotalBeforeTax: ''
storeRestriction:
stores:
- 47847307C1652044
storeGroups:
- Austria
bundle:
productIds:
- '32087'
- '89412'
- '16532'
categoryIds:
- Skincare
discount:
bundle:
type: groupPriceBeforeTax
amount: '149.99'
- id: 01JW4K7MJJKJB1C58F1CP3K2ZQ
workspaceId: '500'
name: Buy 4 pens total for €10.
status: active
description: Buy any 4 pens for a total price of €10.
type: buyXForTotalAmount
imageURL: https://antavo.com
priority: 1
currency: EUR
stackingConfiguration:
selfStackingConfiguration:
isAllowed: true
limit: 5
stackingType: stackable
excludedPromotionIds: null
applicationsResetSchedule: null
restriction:
timeRestriction:
start: 2025-08-01 22:45
end: 2025-09-30 22:45
recurringSchedule: null
applicationsCountLimit: 0
minTotalBeforeTax: '10'
maxTotalBeforeTax: ''
storeRestriction:
stores: []
storeGroups:
- Germany
buyXForTotalAmount:
quantity: 4
item: Stationery
itemType: category
discount:
buyXForTotalAmount:
groupPriceBeforeTax: '10.00'
itemSelectionStrategy: cheapest
- id: 01JW4KAXA32N9ZGEERG7MHMR0X
workspaceId: '500'
name: Buy 3 get 1 free bundle
status: active
description: Buy 3 shirts, get 1 free.
type: buyXGetYFree
imageURL: https://antavo.com
priority: 1
currency: EUR
stackingConfiguration:
selfStackingConfiguration:
isAllowed: true
limit: 3
stackingType: exclusive
excludedPromotionIds: null
applicationsResetSchedule: null
restriction:
timeRestriction:
start: 2025-03-01 22:48
end: 2025-05-31 22:48
recurringSchedule: null
applicationsCountLimit: 0
minTotalBeforeTax: '20'
maxTotalBeforeTax: ''
storeRestriction:
stores:
- 5077595177C60923
- 47847307C1652044
storeGroups:
- Austria
buyXGetYFree:
quantity: 3
item: '2223640'
itemType: product
discount:
buyXGetYFree:
freeProductSelectionStrategy: cheapest
quantity: 1
- id: 01JW4KGCRX5V5213XT9DXZD6QS
workspaceId: '500'
name: Cross-sell winter hats
status: draft
description: Get 25% off hats when buying jackets.
type: crossSelling
imageURL: https://antavo.com
priority: 1
currency: EUR
stackingConfiguration:
selfStackingConfiguration:
isAllowed: true
limit: 0
stackingType: exclusive
excludedPromotionIds: null
applicationsResetSchedule: null
restriction:
timeRestriction:
start: 2025-12-01 22:50
end: 2025-12-06 22:50
recurringSchedule: null
applicationsCountLimit: 0
minTotalBeforeTax: '10'
maxTotalBeforeTax: ''
storeRestriction:
stores: []
storeGroups:
- Germany
crossSelling:
productIds: []
categoryIds:
- Apparel & Accessories > Clothing > Jackets
discount:
crossSelling:
categories:
- categoryId: Apparel & Accessories > Clothing > Hats
type: percentage
amount: '25.00'
product
# --- truncated at 32 KB (99 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/antavo/refs/heads/main/openapi/antavo-promotion-engine-openapi.yml