Promotions

The Promotions API applies and clears promotional codes on a cart. Validation, discount calculation, and stacking rules are owned by the merchant’s platform — Firmly forwards the codes and returns the resulting cart.

​​ Available Endpoints

​​ Result on the Cart

Applied codes appear in the cart’s top-level coupons array (array of strings). Discount amounts surface in:

• cart_discount — total discount applied to the cart
• cart_discount_breakdown — per-promotion breakdown (when the merchant exposes it)
• line_items[].discount and line_items[].line_discount — per-line amounts (when the merchant exposes them)

Totals (sub_total, tax_total, total) are recalculated server-side after each add/clear.