Skip to main content
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
  • 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_statusAvailable OperationsRestrictions
activeAll operations: add/update/remove items, set shipping, apply promos, etc.None - full access
submittedRead-only accessNo modifications allowed
item_not_shippableCan remove items, change shipping addressCannot checkout until resolved
checkout_blockedCan 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

{
  "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