> ## Documentation Index
> Fetch the complete documentation index at: https://developers.firmly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cart Lifecycle

> Understanding cart states and transitions in the Firmly API

Learn how carts progress through different states from creation to order completion.

## Cart States

The cart status is dynamically determined based on the cart's current state and any blocking conditions:

```mermaid theme={null}
graph LR
    A[active] --> B[submitted]
    A --> C[item_not_shippable]
    A --> D[checkout_blocked]
```

### 1. Active State (`cart_status: "active"`)

* Default state for carts with no blocking issues
* Can contain items or be empty
* All operations allowed: add/update/remove items, set shipping, etc.
* Ready for checkout when all required fields are set

### 2. Submitted State (`cart_status: "submitted"`)

* Cart has been successfully submitted as an order
* Indicated by presence of `platform_order_number`
* Cart is read-only - no modifications allowed
* Represents a completed purchase

### 3. Item Not Shippable State (`cart_status: "item_not_shippable"`)

* One or more items cannot be shipped to the selected address
* Checkout is blocked until issue is resolved
* Customer must remove items or change shipping address

### 4. Checkout Blocked State (`cart_status: "checkout_blocked"`)

* Cart has errors preventing checkout
* Cart has validation errors preventing checkout
* Examples: out of stock items, expired promotions, shipping unavailable
* Must resolve all errors before proceeding

## Key Operations by State

| cart\_status         | Available Operations                                                      | Restrictions                             |
| -------------------- | ------------------------------------------------------------------------- | ---------------------------------------- |
| active               | All operations: add/update/remove items, set shipping, apply promos, etc. | None - full access                       |
| submitted            | Read-only access                                                          | No modifications allowed                 |
| item\_not\_shippable | Can remove items, change shipping address                                 | Cannot checkout until resolved           |
| checkout\_blocked    | Can fix blocking issues (remove items, update info)                       | Cannot checkout until all errors cleared |

## Cart Notices (Full Cart API Only)

The Full Cart API (v2) includes a `notices` array that provides information about cart issues:

### Notice Codes

* `ITEM_NOT_SHIPPABLE` - Item cannot be shipped to selected address
* `ITEM_OUT_OF_STOCK` - Item is currently out of stock
* `PROMO_EXPIRED` - Promotional code has expired
* `PROMO_NOT_APPLICABLE` - Promotion doesn't apply to cart contents
* `SHIPPING_NOT_AVAILABLE` - Selected shipping method is unavailable
* `PRICE_INCREASED` - Item price has increased since added to cart
* `PRICE_DECREASED` - Item price has decreased since added to cart

### Notice Structure

```json theme={null}
{
  "code": "ITEM_NOT_SHIPPABLE",
  "severity": "error",
  "item_id": "item_123",  // Optional: specific line item
  "details": {              // Optional: additional context
    "description": "Cannot ship to selected location",
    "reason": "Shipping restrictions apply"
  }
}
```

### Notice Severities

* `error` - Critical issues that may block checkout
* `warning` - Important information that doesn't block checkout
* `info` - Informational messages only

## Best Practices

1. **Check cart\_status before checkout** - Don't allow checkout if status isn't `active`
2. **Display notices to users (V2 API)** - Show cart notices to help users understand issues
3. **Handle status changes** - Cart status can change between API calls based on merchant system state
4. **Resolve blocking issues** - Guide users to fix errors (remove unavailable items, change address, etc.)

## Next Steps

* [Multi-Shipment Structure](/concepts/multi-shipment)
* [API Reference](/api-reference/cart-management/overview)