Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. API Reference
  3. Cart Management
  4. Cart Lifecycle

Cart Lifecycle

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:

​​ 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
  • Buyer must remove items or change shipping address

​​ 4. Checkout Blocked State (cart_status: "checkout_blocked")

  • 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

The cart response 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 


{
  "code": "ITEM_NOT_SHIPPABLE",
  "severity": "error",
  "item_id": "4958451e-0ad5-a545-c865-7b12623e917f",
  "details": {
    "description": "Cannot ship to selected location",
    "reason": "Shipping restrictions apply"
  }

}
Field Required Description
code Yes Notice code (see Notice Codes above)
severity Yes One of error, warning, info
item_id No Present when the notice applies to a specific line item
details No Additional context — free-form description and reason strings

​​ 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 - Show cart notices to help users understand issues (the notices array is returned only in V2 cart responses)
  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