Checkout lifecycle
A checkout session progresses through several states during its lifetime. Understanding these states helps agents determine when a checkout is ready for payment and how to handle transitions.
Status flow
Status definitions
| Status | Description | Next States |
|---|---|---|
not_ready_for_payment | Session created but missing required information (e.g., no fulfillment option selected). Messages array will indicate what's needed. | ready_for_payment, canceled |
ready_for_payment | All required information provided. Session can be completed with payment. | in_progress, canceled |
in_progress | Payment processing has started. Session is locked during payment processing. | completed, ready_for_payment (if payment fails), canceled |
completed | Payment successful and order created. This is a terminal state. | None |
canceled | Session explicitly canceled or expired. This is a terminal state. | None |
State transitions
Creating a session
- New sessions start in
not_ready_for_paymentif required information is missing - Sessions with all required information start in
ready_for_payment
Updating a session
- Sessions remain in their current state unless the update resolves blocking issues
- Providing a fulfillment option when one was required transitions from
not_ready_for_paymenttoready_for_payment
Completing a session
- Transitions from
ready_for_paymenttoin_progresswhen payment processing begins - Transitions from
in_progresstocompletedwhen payment succeeds and order is created - May transition back to
ready_for_paymentif payment processing fails
Canceling a session
- Any non-terminal state can transition to
canceled - Sessions in
completedorcanceledstatus cannot be canceled