code and a messages array. Errors about the subscription’s status also include current_status. A 422 with the code PROMOTION_NOT_APPLICABLE also includes a reason; the other 422 codes carry a code and messages only.
422 Not Applicable
{
"code": "PROMOTION_NOT_APPLICABLE",
"messages": [
"The promotion cannot be applied to this subscription."
],
"reason": "CONDITIONS_NOT_MET"
}
Error codes
| HTTP | code | When |
|---|---|---|
400 | INVALID_PARAMETERS | An update sends promotion together with plan_change. Nothing is changed. Send them in two requests. |
400 | BAD_REQUEST | An update sends promotion together with any other field, such as name or metadata. Nothing is changed. Send the other changes in a separate request. |
404 | PROMOTION_NOT_FOUND | The promotion ID or code is unknown, or belongs to another account. |
409 | PROMOTION_ALREADY_ATTACHED | The plan already has this promotion. |
422 | PROMOTION_NOT_ATTACHED_TO_PLAN | The promotion is applied to a subscription whose plan does not have it. |
422 | PROMOTION_NOT_APPLICABLE | The promotion cannot be attached or applied. The reason says why (see below). |
409 | SUBSCRIPTION_STATUS_NOT_ELIGIBLE | The subscription is not ACTIVE or TRIALING. The response includes current_status. |
409 | SUBSCRIPTION_PROMOTION_NOT_ACTIVE | The request removes a promotion, but the subscription has no active promotion. The response includes current_status: the status of the latest promotion (COMPLETED or ENDED), or null if there was none. |
422 | PROMOTION_ENGINE_UNAVAILABLE | On a payment link’s first payment, the promotion could not be checked. The payment is refused, and nothing is charged. |
422 | PROMOTION_CONTEXT_MISMATCH | On a payment link’s first payment, the payment’s amount or promotion does not match the subscription’s first charge. The payment is refused, and nothing is charged. |
503 | PROMOTION_ENGINE_UNAVAILABLE | The promotions engine did not respond when the promotion was attached or applied. |
504 | PROMOTION_ENGINE_TIMEOUT | The promotions engine did not respond in time when the promotion was attached or applied. |
Reasons for PROMOTION_NOT_APPLICABLE
reason | Meaning |
|---|---|
EXPIRED | The promotion has expired. |
DISABLED | The promotion is disabled. |
NOT_STARTED | The promotion’s start date has not arrived yet. |
USAGE_LIMIT_REACHED | The promotion has no uses left. |
CONDITIONS_NOT_MET | The subscription does not meet the promotion’s conditions: country, currency and amount, payment method type, BIN, or the type of the stored card. Conditions are checked only when the promotion is applied, not on renewals. |
CURRENCY_MISMATCH | A fixed-amount promotion has no amount in the subscription’s currency. |
PROMOTIONS_NOT_ENABLED | Promotions are not turned on for your organization, or the region does not support them. Subscription promotions run in the US region only. |
EXECUTION_TYPE_NOT_SUPPORTED | The subscription has frequency.execution set to MERCHANT. This covers subscriptions that a provider manages, such as Pix Automático. |
SUBSCRIPTION_NOT_ON_A_PLAN | The subscription is not on a plan. Promotions apply only to subscriptions on a plan. |
ZERO_DISCOUNT | The promotion gives no discount on the subscription’s price. |
IDEMPOTENCY_KEY_REUSED | The subscription already used this promotion with a different code. |