Understand coupon and offer states
Customer App can present coupon input, returned coupon state, or offer-backed discount rows for a current cart or checkout. These are different local, server, cart, totals, and analytics stages. Visibility, entered text, a returned row, or a changed total does not prove eligibility, usage consumption, final discount, or safe order placement.
:::warning Coupon actions change cart and financial state
This reference does not instruct applying, replacing, removing, or testing a coupon. Never use a real code or repeat an action to determine whether an earlier request settled.
:::
Legacy/manual and advanced flows differ
| Flow | Current source boundary | Important distinction |
|---|---|---|
| Legacy/manual coupon | A coupon input can request a cart coupon change and later present a returned coupon/removal state. | Apply and removal use a legacy cart path; success/error/telemetry presentation is limited. |
| Advanced offer-backed coupon | A coupon value can request an offer-backed cart change, and returned offer rows can present the accepted state. | Apply, denial, removal, summaries, and analytics use different events and state. |
| Automatic offer state | Returned cart state can include offers without the manual input being the source. | Visibility does not prove a customer entered or consumed a coupon. |
| Multi-business coupon | Group-wide or per-cart controls can start several cart operations. | There is no accepted atomic group coupon transaction or unified rollback. |
Legacy removal and advanced offer-row removal are not interchangeable proof. The current source does not establish one universal coupon flow.
Entered, visible, applied, and removed are separate states
| State | Safe interpretation | What it does not prove |
|---|---|---|
| Empty input | No local coupon value is ready to submit. | Coupon availability or absence. |
| Entered text | A private value is visible in the field. | Eligibility, request settlement, or analytics consent. |
| Entered analytics event | The UI recorded an entry attempt before a result. | That a request succeeded, failed, or had a valid cart identity. |
| Request pending | One or more cart/offer operations may be running. | Single-flight behavior, current intent, or final totals. |
| Returned coupon or offer row | The returned cart contains coupon/offer state for one revision. | Durable usage consumption, non-stackability, order placement, or group-wide success. |
| Remove control or row disappears | A removal presentation or response changed. | That every discount, usage, cart, total, and analytics state settled. |
| Error while text remains visible | The visible field and controller state can disagree. | Safe retry, unchanged cart, or preserved intent. |
Only the latest authorized returned cart revision can establish visible coupon, offer, discount, and total state.
Eligibility and usage consumption differ
Coupon discovery or entry is not eligibility. Eligibility can depend on the current account, project, business, cart contents, fulfillment, address, schedule, order type, customer/guest state, limits, participating targets, and existing offers.
Usage consumption is a later order/financial operation. A cart can appear eligible before placement while another concurrent operation consumes a remaining limit. The accepted contract must reserve and consume usage atomically or return an exact conflict without corrupting the cart.
Do not infer remaining uses, account eligibility, participating businesses, or future order acceptance from a visible coupon or offer.
Replacement, stacking, and concurrency
| Situation | Required boundary |
|---|---|
| Existing coupon or offer | Replacement must be explicit, idempotent, and transactional; silent forced replacement is not accepted. |
| Non-stackable offers | Server must authorize the exact resulting offer set and reject incompatible combinations before cart mutation. |
| Same value submitted twice | One current operation must win; duplicate/replayed work must not consume limits or overwrite newer intent. |
| Different values race | Late earlier responses must not replace the latest authorized cart revision. |
| Multiple businesses | Each target and result must be identified, with all-or-exact-partial settlement and recovery. |
| Shared loading clears early | Another request may still be pending; the cart remains unsettled. |
There is no safe retry rule without an operation receipt that identifies the original request and authoritative resulting cart.
Single and grouped requiredness
Single Checkout can use current order-type and guest-specific validation to require a returned coupon-offer state before Place. A visible coupon string alone may not satisfy that requirement.
Grouped MultiCheckout can present group-wide or per-cart inputs, but the current requiredness, applied-state identity, and refresh behavior do not match single Checkout. A group can remain stale or partial after one or more coupon requests. Do not infer that every group member satisfied a required coupon from one control, one returned cart, or an enabled Place action.
Negative totals and automatic removal
A client safeguard can automatically start coupon removal when its current price input becomes negative. That is an effectful mutation, not validation or proof that the cart recovered correctly.
Negative totals must be rejected by authoritative financial rules before any automatic cart change. Removal, error presentation, totals, usage restoration, analytics, and the current customer intent require one recoverable result. A reopened or malformed error does not establish rollback.
Returned cart and authoritative totals
The client does not calculate coupon discounts authoritatively. A successful response must return one internally consistent current cart containing the accepted coupon/offer state and every affected subtotal, discount, tax, fee, tip, delivery, total, balance, currency, and revision field required for display.
| Displayed change | What remains unproved |
|---|---|
| Discount or offer row appears | Usage reservation/consumption, stack rules, or order acceptance. |
| Subtotal or total changes | Canonical minor-unit amount, currency, fee/tax/tip bases, or latest cart revision. |
| Coupon/offer disappears | Removal settlement, usage restoration, or other active offers. |
| Place becomes enabled | Current server eligibility, operation idempotency, payment, or order placement. |
Address, order type, timing, products, quantities, fees, tips, wallet state, and other cart changes can invalidate previously returned totals.
Analytics and privacy
Coupon values are sensitive marketing and cart context. Entry, applied, denied, and removed analytics can differ by legacy and advanced flow, and some callers can lack the exact cart/group identity required for correct attribution.
A future accepted implementation must require approved analytics purpose and consent, omit the coupon value, bind the event to a minimal current cart/group operation, and emit only after the corresponding authoritative state. Do not place codes, amounts, business/cart/order references, analytics payloads, or screenshots in documentation or support notes.
Error, empty, and unknown outcomes
| Observable outcome | Safe interpretation |
|---|---|
| Coupon area absent | Current configuration/context does not present it; no global availability inference. |
| Input empty | Pre-action local state only. |
| Apply is disabled | Current local input is not ready; no server conclusion. |
| Error appears | Request, eligibility, limit, replacement, cart, or mapping can differ; account existence is not revealed. |
| Error is silent or text remains | Local input/controller/cart state can disagree. |
| One group cart changes | Other carts and group totals remain unresolved. |
| Returned totals are inconsistent or stale | Do not infer an accepted discount or Place authority. |
| Response is lost | Keep coupon, usage, cart, analytics, and order outcome unknown; do not repeat automatically. |
Troubleshooting safely
- Treat visible text, controller state, returned coupon, offer rows, and totals as separate until one current cart revision reconciles them.
- Do not try another value, remove/reapply, change address/type/time, or alter the cart to test eligibility.
- Do not use Place, payment, wallet, or another business as a coupon test.
- Preserve group uncertainty when member carts differ.
- Use only value-free states such as “coupon settlement unresolved,” “returned cart stale,” or “group coupon partial.”
Accessibility and recertification
Coupon input, Apply, disabled/busy state, returned offer/coupon state, removal, confirmation, error, requiredness, totals change, partial, and unknown states need clear semantic names, roles, values, consequences, focus order, and announcements. Large text, keyboard, screen-reader, modal, Back, and focus-return behavior must not hide the current cart state or destructive consequence.
Repeat isolated review after changes to legacy/advanced branches, coupon/offer eligibility, usage limits, replacement/stacking, group behavior, requiredness, negative totals/auto-removal, returned cart/totals, analytics, address/type/time invalidation, placement/payment, accessibility, or App/components/API authority pins. This guide does not certify current financial, privacy, analytics, accessibility, or deployed behavior.
Related guides: Review your cart before checkout · Find offers and promotions · Review fees, taxes, and tips · Understand multi-business checkout · Understand checkout failures and retries · Understand consent and privacy choices