# Apply promotion or gift card

**Flow key:** `promotion-and-gift-card`

## Outcome

An eligible discount or stored-value instrument changes only the intended lines and totals, with correct limits, allocation, balance, tax, and reversal.

## Actors

- Shopper
- Promotion/gift service
- Pricing/tax service
- Support/admin

## Preconditions and entry points

- A deterministic cart exists.
- Active, expired, exhausted, scoped, stackable, and gift-balance test instruments exist.

## Required test data

Use synthetic, isolated, resettable data. Never use real credentials, payment instruments, private customer records, or production notifications.

| Data | Canonical valid seed | Critical variations |
|---|---|---|
| Cart | `CARBON-SKU-001` and eligible/ineligible companion item | below threshold, subscription, sale item, mixed seller |
| Promotion | `CARBON10` | expired, future, usage exhausted, customer-specific, case/whitespace variant |
| Gift card | test card with `$25.00` balance | zero, partial, exact, greater-than-order, disabled |
| Customer | eligible synthetic user | guest, new user, previously redeemed, other tenant/region |
| Concurrency | one checkout session | two tabs or two shoppers redeeming last use |

## Canonical steps

Treat this as the ordinary successful path inferred from common product behavior. Adapt it to observed labels, business rules, APIs, and implementation evidence; do not invent a requirement.

| Step | User or system action | Expected evidence |
|---:|---|---|
| 1 | Open cart or checkout with known totals. | Pre-discount subtotal and eligibility inputs are visible. |
| 2 | Enter and apply the promotion or gift value. | Server validates identity, scope, time, usage, and cart conditions. |
| 3 | Inspect applied lines and totals. | Allocation, stacking, tax, shipping thresholds, currency, and remaining balance are correct. |
| 4 | Change cart, customer, address, or fulfillment. | Eligibility and totals re-evaluate without stale discount. |
| 5 | Remove/reapply and complete order. | Reservation/redemption occurs exactly once at the correct lifecycle point. |
| 6 | Cancel/refund the order. | Usage and stored value restore or remain consumed according to explicit policy. |

## Alternate paths

- Automatic promotion
- Coupon code
- Gift card/store credit
- Multiple stackable offers
- Single-use/referral promotion

## Failure and recovery paths

- Concurrent last redemption
- Quote expires
- Promotion service unavailable
- Payment fails after gift reservation
- Refund restores wrong amount

## Completion oracle

- The stated outcome is true in visible UI and authoritative persisted state.
- Exactly one intended business result and no unintended side effect occurred.
- Identity, tenant, authorization, money/data, lifecycle, notifications, integrations, analytics, and audit agree where applicable.
- Refresh, retry, back/forward, and a second authorized read do not reveal a contradictory result.
- Any partial, delayed, canceled, failed, or unknown outcome is labeled truthfully and has a safe recovery path.

## Evidence to capture

- Entry context, actor, tenant, role, feature flags, locale, time zone, and initial identifiers/state.
- Step-level screenshots or DOM state plus request/response, correlation, job, event, and stable business IDs where available.
- Before/after authoritative records, versions, totals, permissions, lifecycle states, and downstream side effects.
- Notifications, audit events, integration deliveries, retries, deduplication, latency, and recovery evidence.
- Untested branches, unsafe-to-run cases, product decisions, and evidence tier.

## Product decisions to resolve

- Exact eligibility, required data, authorization, and validation rules.
- Which steps are synchronous, asynchronous, optional, skippable, reversible, or irreversible.
- Idempotency, concurrency, timeout, retry, cancellation, and compensation semantics.
- Retention, privacy, notification, audit, performance, accessibility, and localization commitments.

## Related CARBON items

- [currency price totals](../../items/data/currency-price-totals.md)
- [payment](../../items/records/payment.md)
- [concurrency and idempotency](../../items/quality/concurrency-and-idempotency.md)
- [condition and rule expression](../../items/automation/condition-and-rule-expression.md)

[Back to Commerce and billing flows](index.md)
