Spree Commerce

Spree Commerce Carts API

Shopping cart management

GitHub OpenAPI

Operations 22

GET /api/v3/store/carts List active carts
POST /api/v3/store/carts Create a new cart
GET /api/v3/store/carts/{id} Get a cart
PATCH /api/v3/store/carts/{id} Update a cart
DELETE /api/v3/store/carts/{id} Delete a cart
PATCH /api/v3/store/carts/{id}/associate Associate guest cart with authenticated user
POST /api/v3/store/carts/{id}/complete Complete cart
POST /api/v3/store/carts/{cart_id}/discount_codes Apply discount code
DELETE /api/v3/store/carts/{cart_id}/discount_codes/{id} Remove discount code
PATCH /api/v3/store/carts/{cart_id}/fulfillments/{id} Select delivery rate for fulfillment
POST /api/v3/store/carts/{cart_id}/gift_cards Apply gift card
DELETE /api/v3/store/carts/{cart_id}/gift_cards/{id} Remove gift card
POST /api/v3/store/carts/{cart_id}/items Add item to cart
PATCH /api/v3/store/carts/{cart_id}/items/{id} Update line item quantity
DELETE /api/v3/store/carts/{cart_id}/items/{id} Remove line item from cart
POST /api/v3/store/carts/{cart_id}/payment_sessions Create payment session
GET /api/v3/store/carts/{cart_id}/payment_sessions/{id} Get payment session
PATCH /api/v3/store/carts/{cart_id}/payment_sessions/{id} Update payment session
PATCH /api/v3/store/carts/{cart_id}/payment_sessions/{id}/complete Complete payment session
POST /api/v3/store/carts/{cart_id}/payments Create payment
POST /api/v3/store/carts/{cart_id}/store_credits Apply store credit
DELETE /api/v3/store/carts/{cart_id}/store_credits Remove store credit

Documentation

📖
Documentation
https://dev-docs.spreecommerce.org/api-reference/store-api/introduction
📖
Documentation
https://dev-docs.spreecommerce.org/api-reference/admin-api/introduction
📖
Documentation
https://dev-docs.spreecommerce.org/api-reference/platform-api/introduction
📖
Documentation
https://dev-docs.spreecommerce.org/api-reference/storefront-api/introduction
📖
Documentation
https://dev-docs.spreecommerce.org/api-reference/authentication

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/spree-commerce/refs/heads/main/openapi/spree-commerce-carts-api-openapi.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/spree-commerce-carts-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

spree-commerce-carts-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Store Carts API
  contact:
    name: Spree Commerce
    url: https://spreecommerce.org
    email: hello@spreecommerce.org
  description: "Spree Store API v3 - Customer-facing storefront API for building headless commerce experiences.\n\n## Authentication\n\nThe Store API uses two authentication methods:\n\n### API Key (Required)\nAll requests must include a publishable API key in the `x-spree-api-key` header.\n\n### JWT Bearer Token (For authenticated customers)\nAfter login, include the JWT token in the `Authorization: Bearer <token>` header.\n\n### Order Token (For guest checkout)\nWhen creating an order, a `token` is returned. Include this in the `x-spree-token` header\nfor guest access to that specific order.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n  \"error\": {\n    \"code\": \"record_not_found\",\n    \"message\": \"Product not found\"\n  }\n}\n```\n"
  version: v3
servers:
- url: http://{defaultHost}
  variables:
    defaultHost:
      default: localhost:3000
tags:
- name: Carts
  description: Shopping cart management
paths:
  /api/v3/store/carts:
    get:
      summary: List active carts
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Returns all active (incomplete) carts for the authenticated user.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: "import { createClient } from '@spree/sdk'\n\nconst client = createClient({\n  baseUrl: 'https://your-store.com',\n  publishableKey: '<api-key>',\n})\n\nconst carts = await client.carts.list({\n  token: '<token>',\n})"
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: 'Page number (default: 1)'
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: 'Number of results per page (default: 25, max: 100)'
        schema:
          type: integer
      - name: sort
        in: query
        required: false
        description: 'Sort order. Prefix with - for descending. Values: created_at, -created_at, updated_at, -updated_at'
        schema:
          type: string
      - name: q[created_at_gt]
        in: query
        required: false
        description: Filter by created after date (ISO 8601)
        schema:
          type: string
      - name: q[updated_at_gt]
        in: query
        required: false
        description: Filter by updated after date (ISO 8601)
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (items, fulfillments, payments, discounts, billing_address, shipping_address, gift_card, payment_methods). Use "none" to skip associations.
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., total,amount_due,item_count). id is always included.
        schema:
          type: string
      responses:
        '200':
          description: carts listed
          content:
            application/json:
              example:
                data:
                - id: cart_gbHJdmfrXB
                  market_id: null
                  number: R560405209
                  token: iqxaKurjyPCbwiuDRJwhMTLpUQs2SCohKfM
                  email: carly@nicolas.com
                  customer_note: null
                  currency: USD
                  locale: en
                  total_quantity: 1
                  item_total: '10.0'
                  display_item_total: $10.00
                  adjustment_total: '0.0'
                  display_adjustment_total: $0.00
                  discount_total: '0.0'
                  display_discount_total: $0.00
                  tax_total: '0.0'
                  display_tax_total: $0.00
                  included_tax_total: '0.0'
                  display_included_tax_total: $0.00
                  additional_tax_total: '0.0'
                  display_additional_tax_total: $0.00
                  total: '110.0'
                  display_total: $110.00
                  gift_card_total: '0.0'
                  display_gift_card_total: $0.00
                  amount_due: '110.0'
                  display_amount_due: $110.00
                  delivery_total: '100.0'
                  display_delivery_total: $100.00
                  warnings: []
                  store_credit_total: '0.0'
                  display_store_credit_total: $0.00
                  covered_by_store_credit: false
                  current_step: address
                  completed_steps: []
                  requirements:
                  - step: payment
                    field: payment
                    message: Add a payment method
                  shipping_eq_billing_address: false
                  discounts: []
                  items:
                  - id: li_gbHJdmfrXB
                    variant_id: variant_gbHJdmfrXB
                    quantity: 1
                    currency: USD
                    name: Product 584574
                    slug: product-584574
                    options_text: ''
                    price: '10.0'
                    display_price: $10.00
                    total: '10.0'
                    display_total: $10.00
                    adjustment_total: '0.0'
                    display_adjustment_total: $0.00
                    additional_tax_total: '0.0'
                    display_additional_tax_total: $0.00
                    included_tax_total: '0.0'
                    display_included_tax_total: $0.00
                    discount_total: '0.0'
                    display_discount_total: $0.00
                    pre_tax_amount: '10.0'
                    display_pre_tax_amount: $10.00
                    discounted_amount: '10.0'
                    display_discounted_amount: $10.00
                    display_compare_at_amount: $0.00
                    compare_at_amount: null
                    thumbnail_url: null
                    option_values: []
                    digital_links: []
                  fulfillments:
                  - id: ful_gbHJdmfrXB
                    number: H60885401848
                    tracking: U10000
                    tracking_url: null
                    cost: '100.0'
                    display_cost: $100.00
                    total: '100.0'
                    display_total: $100.00
                    discount_total: '0.0'
                    display_discount_total: $0.00
                    additional_tax_total: '0.0'
                    display_additional_tax_total: $0.00
                    included_tax_total: '0.0'
                    display_included_tax_total: $0.00
                    tax_total: '0.0'
                    display_tax_total: $0.00
                    status: pending
                    fulfillment_type: shipping
                    fulfilled_at: null
                    items:
                    - item_id: li_gbHJdmfrXB
                      variant_id: variant_gbHJdmfrXB
                      quantity: 1
                    delivery_method:
                      id: dm_gbHJdmfrXB
                      name: UPS Ground
                      code: UPS_GROUND
                    stock_location:
                      id: sloc_UkLWZg9DAJ
                      state_abbr: NY
                      name: Milissa Kutch
                      address1: 1600 Pennsylvania Ave NW
                      city: Washington
                      zipcode: '20500'
                      country_iso: US
                      country_name: United States of America
                      state_text: NY
                    delivery_rates:
                    - id: dr_gbHJdmfrXB
                      delivery_method_id: dm_gbHJdmfrXB
                      name: UPS Ground
                      selected: true
                      cost: '100.0'
                      total: '100.0'
                      additional_tax_total: '0.0'
                      included_tax_total: '0.0'
                      tax_total: '0.0'
                      display_cost: $100.00
                      display_total: $100.00
                      display_additional_tax_total: $0.00
                      display_included_tax_total: $0.00
                      display_tax_total: $0.00
                      delivery_method:
                        id: dm_gbHJdmfrXB
                        name: UPS Ground
                        code: UPS_GROUND
                  payments: []
                  billing_address:
                    id: addr_uw2YK1rnl0
                    first_name: John
                    last_name: Doe
                    full_name: John Doe
                    address1: 105 Lovely Street
                    address2: Northwest
                    postal_code: '10118'
                    city: New York
                    phone: 555-555-0199
                    company: Company
                    country_name: United States of America
                    country_iso: US
                    state_text: NY
                    state_abbr: NY
                    quick_checkout: false
                    is_default_billing: false
                    is_default_shipping: false
                    state_name: New York
                  shipping_address:
                    id: addr_OIJLhNcSbf
                    first_name: John
                    last_name: Doe
                    full_name: John Doe
                    address1: 106 Lovely Street
                    address2: Northwest
                    postal_code: '10118'
                    city: New York
                    phone: 555-555-0199
                    company: Company
                    country_name: United States of America
                    country_iso: US
                    state_text: NY
                    state_abbr: NY
                    quick_checkout: false
                    is_default_billing: false
                    is_default_shipping: false
                    state_name: New York
                  payment_methods: []
                  gift_card: null
                  market: null
                - id: cart_UkLWZg9DAJ
                  market_id: null
                  number: R504946559
                  token: hC1f3UJxu4NErrgku3ZwU2LT4szVo2mJGUv
                  email: carly@nicolas.com
                  customer_note: null
                  currency: USD
                  locale: en
                  total_quantity: 1
                  item_total: '10.0'
                  display_item_total: $10.00
                  adjustment_total: '0.0'
                  display_adjustment_total: $0.00
                  discount_total: '0.0'
                  display_discount_total: $0.00
                  tax_total: '0.0'
                  display_tax_total: $0.00
                  included_tax_total: '0.0'
                  display_included_tax_total: $0.00
                  additional_tax_total: '0.0'
                  display_additional_tax_total: $0.00
                  total: '110.0'
                  display_total: $110.00
                  gift_card_total: '0.0'
                  display_gift_card_total: $0.00
                  amount_due: '110.0'
                  display_amount_due: $110.00
                  delivery_total: '100.0'
                  display_delivery_total: $100.00
                  warnings: []
                  store_credit_total: '0'
                  display_store_credit_total: $0.00
                  covered_by_store_credit: false
                  current_step: address
                  completed_steps: []
                  requirements:
                  - step: payment
                    field: payment
                    message: Add a payment method
                  shipping_eq_billing_address: false
                  discounts: []
                  items:
                  - id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                    currency: USD
                    name: Product 576038
                    slug: product-576038
                    options_text: ''
                    price: '10.0'
                    display_price: $10.00
                    total: '10.0'
                    display_total: $10.00
                    adjustment_total: '0.0'
                    display_adjustment_total: $0.00
                    additional_tax_total: '0.0'
                    display_additional_tax_total: $0.00
                    included_tax_total: '0.0'
                    display_included_tax_total: $0.00
                    discount_total: '0.0'
                    display_discount_total: $0.00
                    pre_tax_amount: '10.0'
                    display_pre_tax_amount: $10.00
                    discounted_amount: '10.0'
                    display_discounted_amount: $10.00
                    display_compare_at_amount: $0.00
                    compare_at_amount: null
                    thumbnail_url: null
                    option_values: []
                    digital_links: []
                  fulfillments:
                  - id: ful_UkLWZg9DAJ
                    number: H14566689291
                    tracking: U10000
                    tracking_url: null
                    cost: '100.0'
                    display_cost: $100.00
                    total: '100.0'
                    display_total: $100.00
                    discount_total: '0.0'
                    display_discount_total: $0.00
                    additional_tax_total: '0.0'
                    display_additional_tax_total: $0.00
                    included_tax_total: '0.0'
                    display_included_tax_total: $0.00
                    tax_total: '0.0'
                    display_tax_total: $0.00
                    status: pending
                    fulfillment_type: shipping
                    fulfilled_at: null
                    items:
                    - item_id: li_UkLWZg9DAJ
                      variant_id: variant_UkLWZg9DAJ
                      quantity: 1
                    delivery_method:
                      id: dm_UkLWZg9DAJ
                      name: UPS Ground
                      code: UPS_GROUND
                    stock_location:
                      id: sloc_UkLWZg9DAJ
                      state_abbr: NY
                      name: Milissa Kutch
                      address1: 1600 Pennsylvania Ave NW
                      city: Washington
                      zipcode: '20500'
                      country_iso: US
                      country_name: United States of America
                      state_text: NY
                    delivery_rates:
                    - id: dr_UkLWZg9DAJ
                      delivery_method_id: dm_UkLWZg9DAJ
                      name: UPS Ground
                      selected: true
                      cost: '100.0'
                      total: '100.0'
                      additional_tax_total: '0.0'
                      included_tax_total: '0.0'
                      tax_total: '0.0'
                      display_cost: $100.00
                      display_total: $100.00
                      display_additional_tax_total: $0.00
                      display_included_tax_total: $0.00
                      display_tax_total: $0.00
                      delivery_method:
                        id: dm_UkLWZg9DAJ
                        name: UPS Ground
                        code: UPS_GROUND
                  payments: []
                  billing_address:
                    id: addr_EfhxLZ9ck8
                    first_name: John
                    last_name: Doe
                    full_name: John Doe
                    address1: 103 Lovely Street
                    address2: Northwest
                    postal_code: '10118'
                    city: New York
                    phone: 555-555-0199
                    company: Company
                    country_name: United States of America
                    country_iso: US
                    state_text: NY
                    state_abbr: NY
                    quick_checkout: false
                    is_default_billing: false
                    is_default_shipping: false
                    state_name: New York
                  shipping_address:
                    id: addr_VqXmZF31wY
                    first_name: John
                    last_name: Doe
                    full_name: John Doe
                    address1: 104 Lovely Street
                    address2: Northwest
                    postal_code: '10118'
                    city: New York
                    phone: 555-555-0199
                    company: Company
                    country_name: United States of America
                    country_iso: US
                    state_text: NY
                    state_abbr: NY
                    quick_checkout: false
                    is_default_billing: false
                    is_default_shipping: false
                    state_name: New York
                  payment_methods: []
                  gift_card: null
                  market: null
                meta:
                  page: 1
                  limit: 25
                  count: 2
                  pages: 1
                  from: 1
                  to: 2
                  in: 2
                  previous: null
                  next: null
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      summary: Create a new cart
      tags:
      - Carts
      security:
      - api_key: []
      description: 'Creates a new shopping cart. Can be created by guests or authenticated customers.

        Returns a `token` that must be used for guest access to the cart.

        '
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: "import { createClient } from '@spree/sdk'\n\nconst client = createClient({\n  baseUrl: 'https://your-store.com',\n  publishableKey: '<api-key>',\n})\n\n// Create an empty cart\nconst cart = await client.carts.create()\n\n// Create a cart with items\nconst cartWithItems = await client.carts.create({\n  items: [\n    { variant_id: 'variant_abc123', quantity: 2 },\n  ],\n})"
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        description: Bearer JWT token (optional - for authenticated customers)
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: Unique key for request idempotency.
        schema:
          type: string
      responses:
        '201':
          description: cart created
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id: null
                number: R582709141
                token: sbMgF8VrnBNczXfdVscfNEDYvzNFowJwh2s
                email: null
                customer_note: null
                currency: USD
                locale: en
                total_quantity: 0
                item_total: '0.0'
                display_item_total: $0.00
                adjustment_total: '0.0'
                display_adjustment_total: $0.00
                discount_total: '0.0'
                display_discount_total: $0.00
                tax_total: '0.0'
                display_tax_total: $0.00
                included_tax_total: '0.0'
                display_included_tax_total: $0.00
                additional_tax_total: '0.0'
                display_additional_tax_total: $0.00
                total: '0.0'
                display_total: $0.00
                gift_card_total: '0.0'
                display_gift_card_total: $0.00
                amount_due: '0.0'
                display_amount_due: $0.00
                delivery_total: '0.0'
                display_delivery_total: $0.00
                warnings: []
                store_credit_total: '0.0'
                display_store_credit_total: $0.00
                covered_by_store_credit: false
                current_step: address
                completed_steps: []
                requirements:
                - step: cart
                  field: line_items
                  message: Add at least one item to your cart
                - step: address
                  field: email
                  message: Email address is required
                - step: address
                  field: ship_address
                  message: Shipping address is required
                - step: delivery
                  field: shipping_method
                  message: Select a shipping method for all shipments
                shipping_eq_billing_address: true
                discounts: []
                items: []
                fulfillments: []
                payments: []
                billing_address: null
                shipping_address: null
                payment_methods: []
                gift_card: null
                market: null
              schema:
                $ref: '#/components/schemas/Cart'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  type: object
                  description: Write-only key-value metadata (Stripe-style).
                items:
                  type: array
                  description: Items to add to the cart on creation
                  items:
                    type: object
                    properties:
                      variant_id:
                        type: string
                        example: variant_abc123
                        description: Prefixed variant ID
                      quantity:
                        type: integer
                        example: 2
                        description: Quantity (defaults to 1)
                      metadata:
                        type: object
                        additionalProperties: true
                    required:
                    - variant_id
  /api/v3/store/carts/{id}:
    get:
      summary: Get a cart
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: 'Returns a shopping cart by prefixed ID.

        Authorize via x-spree-token header (guest) or JWT Bearer token (authenticated user).

        '
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: "import { createClient } from '@spree/sdk'\n\nconst client = createClient({\n  baseUrl: 'https://your-store.com',\n  publishableKey: '<api-key>',\n})\n\nconst cart = await client.carts.get('cart_abc123', {\n  token: '<token>',\n})"
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Cart prefixed ID (e.g., cart_abc123)
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (items, fulfillments, payments, discounts, billing_address, shipping_address, gift_card, payment_methods). Use "none" to skip associations.
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., total,amount_due,item_count). id is always included.
        schema:
          type: string
      responses:
        '200':
          description: cart with out-of-stock item removed (warnings returned)
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id: null
                number: R911594733
                token: A3bGmry4ZwaVKavBsi7VH9dHvdws3WTttaD
                email: carmine_littel@kshlerin.ca
                customer_note: null
                currency: USD
                locale: en
                total_quantity: 0
                item_total: '0.0'
                display_item_total: $0.00
                adjustment_total: '0.0'
                display_adjustment_total: $0.00
                discount_total: '0.0'
                display_discount_total: $0.00
                tax_total: '0.0'
                display_tax_total: $0.00
                included_tax_total: '0.0'
                display_included_tax_total: $0.00
                additional_tax_total: '0.0'
                display_additional_tax_total: $0.00
                total: '0.0'
                display_total: $0.00
                gift_card_total: '0.0'
                display_gift_card_total: $0.00
                amount_due: '0.0'
                display_amount_due: $0.00
                delivery_total: '0.0'
                display_delivery_total: $0.00
                warnings:
                - code: line_item_removed
                  message: Product 62216 was removed because it was sold out
                  line_item_id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                store_credit_total: '0.0'
                display_store_credit_total: $0.00
                covered_by_store_credit: false
                current_step: address
                completed_steps: []
                requirements:
                - step: cart
                  field: line_items
                  message: Add at least one item to your cart
                - step: delivery
                  field: shipping_method
                  message: Select a shipping method for all shipments
                shipping_eq_billing_address: false
                discounts: []
                items: []
                fulfillments: []
                payments: []
                billing_address:
                  id: addr_UkLWZg9DAJ
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 113 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                shipping_address:
                  id: addr_gbHJdmfrXB
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 114 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                payment_methods: []
                gift_card: null
                market: null
              schema:
                $ref: '#/components/schemas/Cart'
        '404':
          description: cart not found
          content:
            application/json:
              example:
                error:
                  code: cart_not_found
                  message: Cart not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      summary: Update a cart
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Updates cart info (email, addresses, customer note). When addresses change, the order state is reverted to address to ensure shipments are recalculated.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: "import { createClient } from '@spree/sdk'\n\nconst client = createClient({\n  baseUrl: 'https://your-store.com',\n  publishableKey: '<api-key>',\n})\n\nconst cart = await client.carts.update('cart_abc123', {\n  email: 'customer@example.com',\n  shipping_address: {\n    first_name: 'John',\n    last_name: 'Doe',\n    address1: '123 Main St',\n    city: 'New York',\n    postal_code: '10001',\n    country_iso: 'US',\n    state_abbr: 'NY',\n  },\n}, {\n  token: '<token>',\n})"
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: cart updated
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id: null
                number: R537545049
                token: YAfcmRTUDf8ak8FPefKTgpqKXuur3RZrz5S
                email: viola.dickens@mitchellcollier.com
                customer_note: Leave at door
                currency: USD
                locale: en
                total_quantity: 1
                item_total: '19.99'
                display_item_total: $19.99
                adjustment_total: '0.0'
                display_adjustment_total: $0.00
                discount_total: '0.0'
                display_discount_total: $0.00
                tax_total: '0.0'
                display_tax_total: $0.00
                included_tax_total: '0.0'
                display_included_tax_total: $0.00
                additional_tax_total: '0.0'
                display_additional_tax_total: $0.00
                total: '29.99'
                display_total: $29.99
                gift_card_total: '0.0'
                display_gift_card_total: $0.00
                amount_due: '29.99'
                display_amount_due: $29.99
                delivery_total: '10.0'
                display_delivery_total: $10.00
                warnings: []
                store_credit_total: '0.0'
                display_store_credit_total: $0.00
                covered_by_store_credit: false
                current_step: payment
                completed_steps:
                - address
                - delivery
                requirements:
                - step: payment
                  field: payment
                  message: Add a payment method
                shipping_eq_billing_address: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 637993
                  slug: product-637993
                  options_text: ''
                  price: '19.99'
                  display_price: $19.99
                  total: '19.99'
                  display_total: $19.99
                  adjustment_total: '0.0'
                  display_adjustment_total: $0.00
                  additional_tax_total: '0.0'
          

# --- truncated at 32 KB (180 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spree-commerce/refs/heads/main/openapi/spree-commerce-carts-api-openapi.yml