Basket Lifecycle

A POS basket represents a single retail transaction. Understanding its lifecycle is critical for correct POS integration.

State Machine

                    POST /baskets
                         │
                         ▼
                    ┌─────────┐
                    │ Created │
                    └────┬────┘
                         │
           ┌─────────────┴─────────────┐
           │                           │
           ▼                           ▼
    POST .../finalize           POST .../void
           │                           │
           ▼                           ▼
     ┌──────────┐               ┌───────────┐
     │Finalized │               │   Voided  │
     └──────────┘               └───────────┘

State	Description
`Created`	Basket created, offers applied, pending payment
`Finalized`	Payment captured, loyalty points eligible
`Voided`	Transaction cancelled, no loyalty impact

Idempotency

Basket creation is idempotent on posTransactionId. This protects against network retries and duplicate submissions.

Scenario	Request	Response
First submission	`POST /baskets` with `posTransactionId: TXN-001`	`201 Created` + basket object
Retry same transaction	`POST /baskets` with `posTransactionId: TXN-001`	`200 OK` + existing basket (no duplicate)
New transaction	`POST /baskets` with `posTransactionId: TXN-002`	`201 Created` + new basket

Always use a unique posTransactionId per transaction. Using the same ID for a genuinely different transaction will silently return the old basket.

Finalizing a Basket

Call finalize after payment is successfully captured. This locks the basket for reconciliation and makes the transaction eligible for loyalty point earn.

curl -X POST "http://localhost:5003/pos/api/v1/baskets/{basketId}/finalize" \
  -H "X-Api-Key: rsa_live_..."

Returns 204 No Content on success.

Voiding a Basket

Call void if the transaction is cancelled at any point before finalization:

curl -X POST "http://localhost:5003/pos/api/v1/baskets/{basketId}/void" \
  -H "X-Api-Key: rsa_live_..."

A finalized basket cannot be voided. To reverse a finalized transaction, create a reversal loyalty transaction via POST /pos/api/v1/loyalty/earn with a negative points value.

Retrieving a Basket

curl "http://localhost:5003/pos/api/v1/baskets/{basketId}" \
  -H "X-Api-Key: rsa_live_..."

Returns basket details including items, applied offers, totals, and current state.