.png){kind=logo}
Search for promotions
- 22 Nov 2024
- 4 Minutes to read
- Contributors
- Print
- DarkLight
Search for promotions
- Updated on 22 Nov 2024
- 4 Minutes to read
- Contributors
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
Get
/promotion/v1/promotions
Search for specific promotions based on different criteria.
Security
HTTP
Type bearer
Query parameters
filter[promotion][name]
string
Min length1
filter[promotion][description]
string
Min length1
filter[promotion][code]
string
Min length1
page[size]
number
Minimum1
page[cursor]
string
Min length1
Responses
200
Retrieved Promotions
object
data
Array of object
Promotions matching the search criteria.
object
id
string
A unique ID representing the promotion.
Min length1
type
string
The type of the resource
Valid values[ "PROMOTION" ]
createdAt
string (date)
The date and time the promotion was created.
updatedAt
string (date)
The date and time the promotion was last updated.
enabled
boolean
Whether the promotion is enabled to consume. If disabled, new customers will not be able to apply the promotion code, but existing customers with it already applied will be unaffected.
name
string
The name of the promotion.
Min length1
description
string
A detailed description of the promotion.
Min length1
code
string
The unique code to redeem the promotion.
constraint
object
The constraint to determine whether a promotion can be redeemed, including the dates to run for, usage counts, and whether it's only for new customers.
promoStartAt
string (date)
The date and time the promotion starts (inclusive). A promotion must be within these dates for a customer to be able to apply its code.
promoEndAt
string (date)
The date and time the promotion ends (inclusive). A promotion must be within these dates for a customer to be able to apply its code.
maxUsage
number
The maximum number of times the promotion can be redeemed (across all customers).
Minimum1
usageCount
number
The number of times the promotion has been redeemed (across all customers).
Minimum0
subscription
object
newOnly
boolean
Whether the promotion is only for new subscriptions.
typeIds
Array of string
The subscription type IDs the promotion is valid for.
string
Min length1
rules
Array of object
The rules of what orders should receive the promotion effect (such as a monetary discount).
object
effect
object
The effect of the promotion, detailing the percentage or monetary amount to discount.
effectType
string
The type of the effect.
Valid values[ "PERCENTAGE_DISCOUNT", "AMOUNT_DISCOUNT" ]
amount
string
The amount value of the effect.
conditions
Array of object
The conditions to determine if an order should receive the specified effect (such as a percentage discount).
object
conditionType
string
The type of the condition. ORDER_NUMBER_AFTER_APPLIED: The order number as counted from the day the promotion is applied. SUBSCRIPTION_CONTRACT_ORDER_NUMBER: the order number as counted from the start of the subscription contract.
Valid values[ "ORDER_NUMBER_AFTER_APPLIED", "SUBSCRIPTION_CONTRACT_ORDER_NUMBER" ]
value
string
The value of the condition. For ORDER_NUMBER_AFTER_APPLIED, this is the order number counting from the day the promotion is applied. For SUBSCRIPTION_CONTRACT_ORDER_NUMBER, this is the order number of the subscription contract.
meta
object
The metadata of the promotion.
property*
meta
object
cursor
string
property*
links
object
next
string
The next page of results.
prev
string
The previous page of results.
current
string
The current page of results.
400
Bad Request
object
errors
Array of object
Details of problems encountered processing the request.
object
Details of a problem encountered processing the request.
status
string
The HTTP status code applicable to the problem
title
string
A short-human readable description of the problem, this should not change from occurrence to occurrence.
detail
string
A human-readable explanation specific to this occurrence of the problem.
401
Unauthorized
object
errors
Array of object
Details of problems encountered processing the request.
object
Details of a problem encountered processing the request.
status
string
The HTTP status code applicable to the problem
title
string
A short-human readable description of the problem, this should not change from occurrence to occurrence.
detail
string
A human-readable explanation specific to this occurrence of the problem.
403
Forbidden
object
errors
Array of object
Details of problems encountered processing the request.
object
Details of a problem encountered processing the request.
status
string
The HTTP status code applicable to the problem
title
string
A short-human readable description of the problem, this should not change from occurrence to occurrence.
detail
string
A human-readable explanation specific to this occurrence of the problem.
429
Too Many Requests
object
errors
Array of object
Details of problems encountered processing the request.
object
Details of a problem encountered processing the request.
status
string
The HTTP status code applicable to the problem
title
string
A short-human readable description of the problem, this should not change from occurrence to occurrence.
detail
string
A human-readable explanation specific to this occurrence of the problem.
500
Internal Server Error
object
errors
Array of object
Details of problems encountered processing the request.
object
Details of a problem encountered processing the request.
status
string
The HTTP status code applicable to the problem
title
string
A short-human readable description of the problem, this should not change from occurrence to occurrence.
detail
string
A human-readable explanation specific to this occurrence of the problem.
503
Service Unavailable
object
errors
Array of object
Details of problems encountered processing the request.
object
Details of a problem encountered processing the request.
status
string
The HTTP status code applicable to the problem
title
string
A short-human readable description of the problem, this should not change from occurrence to occurrence.
detail
string
A human-readable explanation specific to this occurrence of the problem.
Was this article helpful?