code and messages[]. Only a 422 PROMOTION_NOT_APPLICABLE adds a reason. Branch on code and reason: messages[] is informational text, so never parse it.
The promotions endpoints
These answers belong to Create Promotion, Retrieve Promotion, List Promotions and Disable Promotion.The path: RULE messages
Each message names a field and the rule it broke, for example limits.total: RANGE. A list item carries its index, for example discount.amounts[0].currency: UNKNOWN_CURRENCY. A path has one message: its first failure.
Batch codes
These answers come from Create Promotion Codes. A batch that can’t be made answers422 PROMOTION_NOT_APPLICABLE with one of these reasons, and Yuno stores nothing.
A payment that carries a code
These answers belong to Create Payment. In every one, no payment is created. No answer repeats your code.ENGINE_UNAVAILABLE covers two causes, and the answer does not say which one it is. Both come back with the same reason and the same message.
- Transient: retry later. The promotions service did not answer in time, answered with an error, or Promotions is temporarily disabled by Yuno. Retry the same payment later.
- Not transient: a retry gets the same answer. An automatic promotion wins the selection for this payment and would leave a charge of zero. Send the payment without the code. A payment with no code is charged in full, and the promotion check does not refuse it.
Try again. for both causes, so it does not tell you which one to retry. If the same payment still gets ENGINE_UNAVAILABLE after you retry later, send it without the code. The customer then pays the full price and loses the discount of that code for that payment.
The text of each reason:
The
PROMOTION_SUBSCRIPTION_UNSUPPORTED message is YUNO_PROMOTION discount lines are not supported on subscriptions. for a payment that carries a subscription, and Subscription payments cannot carry a promotion quote. for an external_subscription or an external_invoice. The PROMOTION_CONTEXT_MISMATCH message is The payment context does not match the promotion quote. Those two bodies have no reason.
When the code becomes a quote, the payment goes on as a payment with a quote, and the rejections in The customer pays the quoted price, or the payment is rejected apply to it.
A quote request that carries a code
Create Promotion Quote answers a request with acode in these ways. The reason and the message of each are the ones in the tables above.
A quote request sends no idempotency key, so it never answers
IDEMPOTENCY_KEY_REUSED. It answers ZERO_CHARGE for a code that leaves a charge of zero, as a payment does. A quote request for a code that applies gets a 200 preview, with no quote_id and no expires_at. An automatic promotion that would leave a charge of zero gets 204.