Product Discounts
Discounts and promotions.
Get promotion by code
/discounts/promotions/promo-code/{promoCode}Look up a promotion by its promotional code to check availability and details.
Path parameters
promostringrequiredThe promotional code to look up.
Responses
200Promotion details including associated discount information.
application/json
Promotion details including associated discount information.
Promotion details including associated discount information.
objectPromotion
A promotion that applies a discount when the promotional code is used.
promotionstringrequiredThe unique identifier for the promotion.
promostringrequiredThe promotional code that customers can use to activate this promotion.
discountintegerrequiredThe number of months the discount will be applied.
validstringdateWhen the promotion becomes valid and can be used.
If not provided, the promotion is valid immediately.
validstringdateWhen the promotion expires and can no longer be used.
If not provided, the promotion does not expire.
discountstringrequiredThe unique identifier for the discount that this promotion applies to.
discountobjectrequiredEssential discount information without sensitive details.
Show child attributes
discountstringrequiredThe unique identifier for the discount.
descriptionstringrequiredA description of what the discount provides.
tagstringA short label or category for the discount.
createdstringdate-timeWhen the discount was created.
updatedstringdate-timeWhen the discount was last updated.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/discounts/promotions/promo-code/SUMMER25 \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/discounts/promotions/promo-code/SUMMER25', {
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.get(
"https://apiv2.example.com/api/v2/discounts/promotions/promo-code/SUMMER25",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/discounts/promotions/promo-code/SUMMER25"
req, _ := http.NewRequest("GET", requestUrl, nil)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"promotionId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"promoCode": "SUMMER25",
"discountPeriodMonths": 12,
"validFrom": "2024-02-01",
"validTo": "2024-02-01",
"discountId": "80df6fdf-c450-406e-948b-f77d4ac1cdb8",
"discount": {
"discountId": "80df6fdf-c450-406e-948b-f77d4ac1cdb8",
"description": "25% Off Summer Promo",
"tag": "SUMMER25",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}