---
openapi: 3.0.3
info:
  title: Store 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.

    ## Authentication

    The Store API uses two authentication methods:

    ### API Key (Required)
    All requests must include a publishable API key in the `x-spree-api-key` header.

    ### JWT Bearer Token (For authenticated customers)
    After login, include the JWT token in the `Authorization: Bearer <token>` header.

    ### Order Token (For guest checkout)
    When creating an order, a `token` is returned. Include this in the `x-spree-token` header
    for guest access to that specific order.

    ## Response Format

    All responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.

    ## Error Handling

    Errors return a consistent format:
    ```json
    {
      "error": {
        "code": "record_not_found",
        "message": "Product not found"
      }
    }
    ```
  version: v3
paths:
  "/api/v3/store/customers/me/addresses":
    get:
      summary: List customer addresses
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Returns all addresses in the customer address book
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const addresses = await client.customer.addresses.list({}, {
            token: '<token>',
          })
      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
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: addresses found
          content:
            application/json:
              example:
                data:
                - id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 72 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
                - id: addr_gbHJdmfrXB
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 71 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: true
                  is_default_shipping: false
                  state_name: New York
                - id: addr_UkLWZg9DAJ
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 70 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: true
                  state_name: New York
                meta:
                  page: 1
                  limit: 25
                  count: 3
                  pages: 1
                  from: 1
                  to: 3
                  in: 3
                  previous:
                  next:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Address"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    post:
      summary: Create an address
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Adds a new address to the customer address book
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const address = await client.customer.addresses.create({
            first_name: 'John',
            last_name: 'Doe',
            address1: '123 Main St',
            city: 'New York',
            postal_code: '10001',
            country_iso: 'US',
            state_abbr: 'NY',
            phone: '+1 555 123 4567',
          }, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '201':
          description: address created
          content:
            application/json:
              example:
                id: addr_VqXmZF31wY
                first_name: John
                last_name: Doe
                full_name: John Doe
                address1: 123 Main St
                address2:
                postal_code: '10001'
                city: New York
                phone: "+1 555 123 4567"
                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
              schema:
                "$ref": "#/components/schemas/Address"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: First Name can't be blank, Last Name can't be blank, Address
                    can't be blank, City can't be blank, Country can't be blank, and
                    Zip Code can't be blank
                  details:
                    firstname:
                    - can't be blank
                    lastname:
                    - can't be blank
                    address1:
                    - can't be blank
                    city:
                    - can't be blank
                    country:
                    - can't be blank
                    zipcode:
                    - can't be blank
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                  example: John
                last_name:
                  type: string
                  example: Doe
                address1:
                  type: string
                  example: 123 Main St
                address2:
                  type: string
                  example: Apt 4B
                city:
                  type: string
                  example: New York
                postal_code:
                  type: string
                  example: '10001'
                phone:
                  type: string
                  example: "+1 555 123 4567"
                company:
                  type: string
                  example: Acme Inc
                country_iso:
                  type: string
                  example: US
                  description: ISO 3166-1 alpha-2 country code (e.g., "US", "DE")
                state_abbr:
                  type: string
                  example: NY
                  description: ISO 3166-2 subdivision code without country prefix
                    (e.g., "CA", "NY")
                state_name:
                  type: string
                  example: New York
                  description: State name - for countries without predefined states
                is_default_billing:
                  type: boolean
                  example: true
                  description: Set as default billing address
                is_default_shipping:
                  type: boolean
                  example: true
                  description: Set as default shipping address
              required:
              - first_name
              - last_name
              - address1
              - city
              - postal_code
              - country_iso
  "/api/v3/store/customers/me/addresses/{id}":
    get:
      summary: Get an address
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const address = await client.customer.addresses.get('addr_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: address found
          content:
            application/json:
              example:
                id: addr_EfhxLZ9ck8
                first_name: John
                last_name: Doe
                full_name: John Doe
                address1: 84 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
              schema:
                "$ref": "#/components/schemas/Address"
        '404':
          description: address not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Address not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update an address
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const address = await client.customer.addresses.update('addr_abc123', {
            city: 'Los Angeles',
          }, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: address updated
          content:
            application/json:
              example:
                id: addr_EfhxLZ9ck8
                first_name: John
                last_name: Doe
                full_name: John Doe
                address1: 90 Lovely Street
                address2: Northwest
                postal_code: '10118'
                city: Los Angeles
                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
              schema:
                "$ref": "#/components/schemas/Address"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                  example: John
                last_name:
                  type: string
                  example: Doe
                address1:
                  type: string
                  example: 456 Oak Ave
                city:
                  type: string
                  example: Los Angeles
                is_default_billing:
                  type: boolean
                  example: true
                  description: Set as default billing address
                is_default_shipping:
                  type: boolean
                  example: true
                  description: Set as default shipping address
    delete:
      summary: Delete an address
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          await client.customer.addresses.delete('addr_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: address deleted
        '404':
          description: address not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Address not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/auth/login":
    post:
      summary: Login
      tags:
      - Authentication
      security:
      - api_key: []
      description: Authenticates a customer with email/password and returns a JWT
        token
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const auth = await client.auth.login({
            email: 'customer@example.com',
            password: 'password123',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: login successful
          content:
            application/json:
              example:
                token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImFjMTYxZjIyLTY2ODUtNDM0My1hZjhlLWFmNmZiY2Q4NzA3ZCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc5MzkwNzE2fQ.BuOWlcghPrLfW7-ka3a2yD1Giq5DAG-5amAPCOsJOvY
                refresh_token: PZZGJT4udwGkyKEPgs4WRtus
                user:
                  id: cus_UkLWZg9DAJ
                  email: test@example.com
                  first_name: Henriette
                  last_name: Stamm
                  phone:
                  accepts_email_marketing: false
                  full_name: Henriette Stamm
                  available_store_credit_total: '0'
                  display_available_store_credit_total: "$0.00"
                  addresses: []
                  default_billing_address:
                  default_shipping_address:
              schema:
                "$ref": "#/components/schemas/AuthResponse"
        '401':
          description: missing API key
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: Valid API key required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                provider:
                  type: string
                  example: email
                  description: 'Authentication provider (default: email)'
                email:
                  type: string
                  format: email
                  example: customer@example.com
                password:
                  type: string
                  example: password123
              required:
              - email
              - password
  "/api/v3/store/auth/refresh":
    post:
      summary: Refresh token
      tags:
      - Authentication
      security:
      - api_key: []
      description: Exchanges a refresh token for a new access JWT and rotated refresh
        token. No Authorization header needed.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const auth = await client.auth.refresh({
            refresh_token: 'rt_xxx',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: token refreshed
          content:
            application/json:
              example:
                token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6Ijg2NTFkMTJlLTRiMTItNDZhNi1hYjgzLTY4MjI1YWNhN2FhYyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc5MzkwNzE3fQ.mz2V3U-_6wrTzoLytYOOGc7mgH7eG71jQ_oA4mIHGtY
                refresh_token: sRppucnbaakQTvpFCoJArcde
                user:
                  id: cus_UkLWZg9DAJ
                  email: test@example.com
                  first_name: Richard
                  last_name: Larson
                  phone:
                  accepts_email_marketing: false
                  full_name: Richard Larson
                  available_store_credit_total: '0'
                  display_available_store_credit_total: "$0.00"
                  addresses: []
                  default_billing_address:
                  default_shipping_address:
              schema:
                "$ref": "#/components/schemas/AuthResponse"
        '401':
          description: missing or invalid refresh token
          content:
            application/json:
              example:
                error:
                  code: invalid_refresh_token
                  message: Invalid or expired refresh token
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                refresh_token:
                  type: string
                  description: Refresh token from login response
              required:
              - refresh_token
  "/api/v3/store/auth/logout":
    post:
      summary: Logout
      tags:
      - Authentication
      security:
      - api_key: []
        bearer_auth: []
      description: Revokes the refresh token, effectively logging the customer out.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          await client.auth.logout({
            refresh_token: 'rt_xxx',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '204':
          description: logout without refresh token (no-op)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                refresh_token:
                  type: string
                  description: Refresh token to revoke
  "/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'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const carts = await client.carts.list({
            token: '<token>',
          })
      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:
                  number: R560405209
                  token: iqxaKurjyPCbwiuDRJwhMTLpUQs2SCohKfM
                  email: carly@nicolas.com
                  customer_note:
                  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:
                    thumbnail_url:
                    option_values: []
                    digital_links: []
                  fulfillments:
                  - id: ful_gbHJdmfrXB
                    number: H60885401848
                    tracking: U10000
                    tracking_url:
                    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:
                    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:
                  market:
                - id: cart_UkLWZg9DAJ
                  market_id:
                  number: R504946559
                  token: hC1f3UJxu4NErrgku3ZwU2LT4szVo2mJGUv
                  email: carly@nicolas.com
                  customer_note:
                  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:
                    thumbnail_url:
                    option_values: []
                    digital_links: []
                  fulfillments:
                  - id: ful_UkLWZg9DAJ
                    number: H14566689291
                    tracking: U10000
                    tracking_url:
                    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:
                    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:
                  market:
                meta:
                  page: 1
                  limit: 25
                  count: 2
                  pages: 1
                  from: 1
                  to: 2
                  in: 2
                  previous:
                  next:
        '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'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          // Create an empty cart
          const cart = await client.carts.create()

          // Create a cart with items
          const cartWithItems = await client.carts.create({
            items: [
              { variant_id: 'variant_abc123', quantity: 2 },
            ],
          })
      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:
                number: R582709141
                token: sbMgF8VrnBNczXfdVscfNEDYvzNFowJwh2s
                email:
                customer_note:
                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:
                shipping_address:
                payment_methods: []
                gift_card:
                market:
              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'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const cart = await client.carts.get('cart_abc123', {
            token: '<token>',
          })
      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:
                number: R911594733
                token: A3bGmry4ZwaVKavBsi7VH9dHvdws3WTttaD
                email: carmine_littel@kshlerin.ca
                customer_note:
                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:
                market:
              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'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const cart = await client.carts.update('cart_abc123', {
            email: 'customer@example.com',
            shipping_address: {
              first_name: 'John',
              last_name: 'Doe',
              address1: '123 Main St',
              city: 'New York',
              postal_code: '10001',
              country_iso: 'US',
              state_abbr: 'NY',
            },
          }, {
            token: '<token>',
          })
      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:
                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'
                  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: '19.99'
                  display_pre_tax_amount: "$19.99"
                  discounted_amount: '19.99'
                  display_discounted_amount: "$19.99"
                  display_compare_at_amount: "$0.00"
                  compare_at_amount:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments:
                - id: ful_gbHJdmfrXB
                  number: H35255737216
                  tracking:
                  tracking_url:
                  cost: '10.0'
                  display_cost: "$10.00"
                  total: '10.0'
                  display_total: "$10.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:
                  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: Chung O'Keefe
                    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_UkLWZg9DAJ
                    name: UPS Ground
                    selected: true
                    cost: '10.0'
                    total: '10.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    display_cost: "$10.00"
                    display_total: "$10.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: 117 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: 118 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:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  example: customer@example.com
                customer_note:
                  type: string
                  example: Leave at door
                metadata:
                  type: object
                  additionalProperties: true
                shipping_address_id:
                  type: string
                  description: Existing address ID to use as shipping address
                  example: addr_abc123
                billing_address_id:
                  type: string
                  description: Existing address ID to use as billing address
                  example: addr_def456
                billing_address:
                  type: object
                  properties:
                    first_name:
                      type: string
                    last_name:
                      type: string
                    address1:
                      type: string
                    address2:
                      type: string
                    city:
                      type: string
                    postal_code:
                      type: string
                    phone:
                      type: string
                    company:
                      type: string
                    country_iso:
                      type: string
                    state_abbr:
                      type: string
                shipping_address:
                  type: object
                  properties:
                    first_name:
                      type: string
                    last_name:
                      type: string
                    address1:
                      type: string
                    address2:
                      type: string
                    city:
                      type: string
                    postal_code:
                      type: string
                    phone:
                      type: string
                    company:
                      type: string
                    country_iso:
                      type: string
                    state_abbr:
                      type: string
    delete:
      summary: Delete a cart
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Deletes/abandons the cart.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          await client.carts.delete('cart_abc123', {
            token: '<token>',
          })
      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
        schema:
          type: string
      responses:
        '204':
          description: cart deleted
  "/api/v3/store/carts/{id}/associate":
    patch:
      summary: Associate guest cart with authenticated user
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: |
        Associates a guest cart with the currently authenticated user.
        Requires JWT authentication. The cart must not belong to another user.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const cart = await client.carts.associate('cart_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: cart associated successfully
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R231347948
                token: RnHB5VgA21xi2SsJFvCKad7qbWLdo47QGnV
                email: reinaldo@hesselschimmel.info
                customer_note:
                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_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 653132
                  slug: product-653132
                  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:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments:
                - id: ful_UkLWZg9DAJ
                  number: H45239248483
                  tracking: U10000
                  tracking_url:
                  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:
                  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: Dexter Boyer
                    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_UkLWZg9DAJ
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 123 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: 124 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:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
        '401':
          description: unauthorized - JWT required
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/carts/{id}/complete":
    post:
      summary: Complete cart
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Completes the cart and finalizes the purchase. Returns an Order
        (not Cart).
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const order = await client.carts.complete('cart_abc123', {
            token: '<token>',
          })
      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
        schema:
          type: string
      responses:
        '200':
          description: cart completed
          content:
            application/json:
              example:
                id: or_UkLWZg9DAJ
                market_id:
                channel_id: ch_UkLWZg9DAJ
                number: R264397359
                email: enda@becker.ca
                customer_note:
                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: '0.0'
                display_amount_due: "$0.00"
                delivery_total: '10.0'
                display_delivery_total: "$10.00"
                fulfillment_status: backorder
                payment_status: paid
                completed_at: '2026-05-21T18:12:04.119Z'
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 679791
                  slug: product-679791
                  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'
                  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: '19.99'
                  display_pre_tax_amount: "$19.99"
                  discounted_amount: '19.99'
                  display_discounted_amount: "$19.99"
                  display_compare_at_amount: "$0.00"
                  compare_at_amount:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments:
                - id: ful_gbHJdmfrXB
                  number: H72789993064
                  tracking:
                  tracking_url:
                  cost: '10.0'
                  display_cost: "$10.00"
                  total: '10.0'
                  display_total: "$10.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:
                  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: Gabriela Kemmer
                    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_UkLWZg9DAJ
                    name: UPS Ground
                    selected: true
                    cost: '10.0'
                    total: '10.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    display_cost: "$10.00"
                    display_total: "$10.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:
                - id: py_UkLWZg9DAJ
                  payment_method_id: pm_UkLWZg9DAJ
                  response_code: BGS-6d4860421892
                  number: PDDA4ACI
                  amount: '29.99'
                  display_amount: "$29.99"
                  status: completed
                  source_type: credit_card
                  source_id: card_UkLWZg9DAJ
                  source:
                    id: card_UkLWZg9DAJ
                    brand: visa
                    last4: '1111'
                    month: 12
                    year: 2027
                    name: Spree Commerce
                    default: false
                    gateway_payment_profile_id:
                  payment_method:
                    id: pm_UkLWZg9DAJ
                    name: Check
                    description:
                    type: check
                    session_required: false
                    source_required: false
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 131 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: 132 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
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Order"
        '422':
          description: cannot complete
          content:
            application/json:
              example:
                error:
                  code: cart_cannot_complete
                  message: No payment found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/categories":
    get:
      summary: List categories
      tags:
      - Product Catalog
      security:
      - api_key: []
      description: Returns a paginated list of categories for the current store
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const categories = await client.categories.list({
            page: 1,
            limit: 25,
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: q[name_cont]
        in: query
        required: false
        description: Filter by name
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: categories found
          content:
            application/json:
              example:
                data:
                - id: ctg_UkLWZg9DAJ
                  name: taxonomy_1
                  permalink: taxonomy-1
                  position: 0
                  depth: 0
                  meta_title:
                  meta_description:
                  meta_keywords:
                  children_count: 1
                  parent_id:
                  description: ''
                  description_html: ''
                  image_url:
                  square_image_url:
                  is_root: true
                  is_child: false
                  is_leaf: false
                - id: ctg_gbHJdmfrXB
                  name: taxon_1
                  permalink: taxonomy-1/taxon-1
                  position: 0
                  depth: 1
                  meta_title:
                  meta_description:
                  meta_keywords:
                  children_count: 1
                  parent_id: ctg_UkLWZg9DAJ
                  description: ''
                  description_html: ''
                  image_url:
                  square_image_url:
                  is_root: false
                  is_child: true
                  is_leaf: false
                - id: ctg_EfhxLZ9ck8
                  name: taxon_2
                  permalink: taxonomy-1/taxon-1/taxon-2
                  position: 0
                  depth: 2
                  meta_title:
                  meta_description:
                  meta_keywords:
                  children_count: 0
                  parent_id: ctg_gbHJdmfrXB
                  description: ''
                  description_html: ''
                  image_url:
                  square_image_url:
                  is_root: false
                  is_child: true
                  is_leaf: true
                meta:
                  page: 1
                  limit: 25
                  count: 3
                  pages: 1
                  from: 1
                  to: 3
                  in: 3
                  previous:
                  next:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Category"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: Valid API key required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/categories/{id}":
    get:
      summary: Get a category
      tags:
      - Product Catalog
      security:
      - api_key: []
      description: Returns a single category by permalink or prefix ID
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const category = await client.categories.get('categories/clothing/shirts', {
            expand: ['children'],
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Category permalink (e.g., clothing/shirts) or prefix ID (e.g.,
          ctg_abc123)
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Expand associations (children, parent, ancestors, custom_fields)
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: category found by prefix ID
          content:
            application/json:
              example:
                id: ctg_gbHJdmfrXB
                name: taxon_10
                permalink: taxonomy-7/taxon-10
                position: 0
                depth: 1
                meta_title:
                meta_description:
                meta_keywords:
                children_count: 1
                parent_id: ctg_UkLWZg9DAJ
                description: ''
                description_html: ''
                image_url:
                square_image_url:
                is_root: false
                is_child: true
                is_leaf: false
              schema:
                "$ref": "#/components/schemas/Category"
        '404':
          description: category from other store not accessible
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Category not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: Valid API key required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/countries":
    get:
      summary: List countries
      tags:
      - Markets
      security:
      - api_key: []
      description: Returns countries available in the store. Use ?expand=market to
        include market details (currency, locale, tax_inclusive).
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const countries = await client.countries.list()
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: countries found
          content:
            application/json:
              example:
                data:
                - iso: DE
                  iso3: IS39
                  name: Germany
                  states_required: false
                  zipcode_required: true
                - iso: US
                  iso3: USA
                  name: United States of America
                  states_required: true
                  zipcode_required: true
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Country"
                required:
                - data
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: Valid API key required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/countries/{iso}":
    get:
      summary: Get a country
      tags:
      - Markets
      security:
      - api_key: []
      description: Returns a single country by ISO code. Supports ?expand=states for
        address forms and ?expand=market for market details.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const country = await client.countries.get('US')
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: iso
        in: path
        required: true
        description: Country ISO 3166-1 alpha-2 code (e.g., "US", "DE")
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: country found
          content:
            application/json:
              example:
                iso: US
                iso3: USA
                name: United States of America
                states_required: true
                zipcode_required: true
              schema:
                type: object
                properties:
                  iso:
                    type: string
                  iso3:
                    type: string
                  name:
                    type: string
                  states_required:
                    type: boolean
                  zipcode_required:
                    type: boolean
                required:
                - iso
                - iso3
                - name
                - states_required
                - zipcode_required
        '404':
          description: country not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Country not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/customers/me/credit_cards":
    get:
      summary: List saved credit cards
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Returns all saved credit cards for the authenticated customer
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const cards = await client.customer.creditCards.list({}, {
            token: '<token>',
          })
      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
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: credit cards found
          content:
            application/json:
              example:
                data:
                - id: card_UkLWZg9DAJ
                  brand: visa
                  last4: '1111'
                  month: 12
                  year: 2027
                  name: Spree Commerce
                  default: false
                  gateway_payment_profile_id:
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/CreditCard"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/customers/me/credit_cards/{id}":
    get:
      summary: Get a credit card
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Returns a saved credit card by its ID
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const card = await client.customer.creditCards.get('card_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: credit card found
          content:
            application/json:
              example:
                id: card_UkLWZg9DAJ
                brand: visa
                last4: '1111'
                month: 12
                year: 2027
                name: Spree Commerce
                default: false
                gateway_payment_profile_id:
              schema:
                "$ref": "#/components/schemas/CreditCard"
        '404':
          description: credit card not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Credit card not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    delete:
      summary: Delete a credit card
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Removes a saved credit card from the customer account
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          await client.customer.creditCards.delete('card_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: credit card deleted
        '404':
          description: credit card not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Credit card not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/currencies":
    get:
      summary: List supported currencies
      tags:
      - Markets
      security:
      - api_key: []
      description: Returns currencies supported by the store (derived from markets)
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const currencies = await client.currencies.list()
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: currencies found
          content:
            application/json:
              example:
                data:
                - iso_code: USD
                  name: United States Dollar
                  symbol: "$"
                - iso_code: EUR
                  name: Euro
                  symbol: "€"
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Currency"
                required:
                - data
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: Valid API key required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/password_resets":
    post:
      summary: Request a password reset
      tags:
      - Authentication
      security:
      - api_key: []
      description: Sends a password reset email if an account exists for the given
        email address. Always returns 202 Accepted to prevent email enumeration.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          await client.passwordResets.create({
            email: 'customer@example.com',
            redirect_url: 'https://myshop.com/reset-password',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '202':
          description: email not found (same response to prevent enumeration)
          content:
            application/json:
              example:
                message: If an account exists for that email, password reset instructions
                  have been sent.
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: missing API key
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: Valid API key required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  example: customer@example.com
                  description: Email address of the account to reset
                redirect_url:
                  type: string
                  format: uri
                  example: https://myshop.com/reset-password
                  description: URL to redirect the user to after clicking the reset
                    link. Validated against the store's allowed origins.
              required:
              - email
  "/api/v3/store/password_resets/{token}":
    patch:
      summary: Reset password with token
      tags:
      - Authentication
      security:
      - api_key: []
      description: Resets the password using a token received via email. Returns a
        JWT token on success (auto-login).
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const auth = await client.passwordResets.update(
            'reset-token-from-email',
            {
              password: 'newsecurepassword',
              password_confirmation: 'newsecurepassword',
            }
          )
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: token
        in: path
        required: true
        description: Password reset token from the email
        schema:
          type: string
      responses:
        '200':
          description: password reset successful
          content:
            application/json:
              example:
                token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImRhYjViODFiLWZkODQtNDU1NC1iZjJkLWFlYWUzZWJjYWEyZiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc5MzkwNzMwfQ.A7ZqLfCc-PN69iuQHuMdSM6U_leCsrC5gV5ABpuwtbc
                refresh_token: S8rzSN7cnzSAwzjbRFiTKHL8
                user:
                  id: cus_UkLWZg9DAJ
                  email: customer@example.com
                  first_name: Denita
                  last_name: Rau
                  phone:
                  accepts_email_marketing: false
                  full_name: Denita Rau
                  available_store_credit_total: '0'
                  display_available_store_credit_total: "$0.00"
                  addresses: []
                  default_billing_address:
                  default_shipping_address:
              schema:
                "$ref": "#/components/schemas/AuthResponse"
        '422':
          description: password confirmation mismatch
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Password confirmation doesn't match Password
                  details:
                    password_confirmation:
                    - doesn't match Password
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '401':
          description: missing API key
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: Valid API key required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  type: string
                  minLength: 6
                  example: newsecurepassword
                password_confirmation:
                  type: string
                  example: newsecurepassword
              required:
              - password
              - password_confirmation
  "/api/v3/store/customers/me/orders":
    get:
      summary: List orders
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Returns a paginated list of completed orders for the authenticated
        customer.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const orders = await client.customer.orders.list(
            {
              completed_at_gt: '2026-01-01',
              sort: '-completed_at',
            },
            { token: '<token>' },
          )
      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: completed_at,
          -completed_at, total, -total, number, -number'
        schema:
          type: string
      - name: q[completed_at_gt]
        in: query
        required: false
        description: Filter by completed after date (ISO 8601)
        schema:
          type: string
      - name: q[completed_at_lt]
        in: query
        required: false
        description: Filter by completed before date (ISO 8601)
        schema:
          type: string
      - name: q[number_eq]
        in: query
        required: false
        description: Filter by exact order number (e.g., R123456)
        schema:
          type: string
      - name: q[state_eq]
        in: query
        required: false
        description: Filter by order state (complete, returned, canceled)
        schema:
          type: string
      - name: q[payment_state_eq]
        in: query
        required: false
        description: Filter by payment state (paid, balance_due, credit_owed, void,
          failed)
        schema:
          type: string
      - name: q[total_gteq]
        in: query
        required: false
        description: Filter by minimum total
        schema:
          type: number
      - name: q[total_lteq]
        in: query
        required: false
        description: Filter by maximum total
        schema:
          type: number
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (items, fulfillments,
          payments, discounts, billing_address, shipping_address, gift_card). 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: orders listed
          content:
            application/json:
              example:
                data:
                - id: or_UkLWZg9DAJ
                  market_id:
                  channel_id: ch_UkLWZg9DAJ
                  number: R600105954
                  email: adria@okuneva.biz
                  customer_note:
                  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"
                  fulfillment_status:
                  payment_status:
                  completed_at: '2026-05-21T18:12:11.464Z'
                  store_credit_total: '0.0'
                  display_store_credit_total: "$0.00"
                  covered_by_store_credit: false
                  discounts: []
                  items:
                  - id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                    currency: USD
                    name: Product 767917
                    slug: product-767917
                    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:
                    thumbnail_url:
                    option_values: []
                    digital_links: []
                  fulfillments:
                  - id: ful_UkLWZg9DAJ
                    number: H90711662288
                    tracking: U10000
                    tracking_url:
                    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:
                    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: Annie Marks
                      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_UkLWZg9DAJ
                      name: UPS Ground
                      selected: true
                      cost: '10.0'
                      total: '10.0'
                      additional_tax_total: '0.0'
                      included_tax_total: '0.0'
                      tax_total: '0.0'
                      display_cost: "$10.00"
                      display_total: "$10.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: 151 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: 152 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
                  gift_card:
                  market:
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Order"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/customers/me/orders/{id}":
    get:
      summary: Get an order
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Returns a single completed order for the authenticated customer.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const order = await client.customer.orders.get('or_abc123', {}, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Order prefixed ID
        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). 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: order found
          content:
            application/json:
              example:
                id: or_UkLWZg9DAJ
                market_id:
                channel_id: ch_UkLWZg9DAJ
                number: R060306455
                email: josefine.friesen@armstrong.co.uk
                customer_note:
                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"
                fulfillment_status:
                payment_status:
                completed_at: '2026-05-21T18:12:12.168Z'
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 787709
                  slug: product-787709
                  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:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments:
                - id: ful_UkLWZg9DAJ
                  number: H26048702619
                  tracking: U10000
                  tracking_url:
                  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:
                  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: Nyla Rau
                    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_UkLWZg9DAJ
                    name: UPS Ground
                    selected: true
                    cost: '10.0'
                    total: '10.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    display_cost: "$10.00"
                    display_total: "$10.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: 157 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: 158 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
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Order"
        '404':
          description: order belongs to another user
          content:
            application/json:
              example:
                error:
                  code: order_not_found
                  message: Order not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/customers":
    post:
      summary: Register a new customer
      tags:
      - Customers
      security:
      - api_key: []
      description: Creates a new customer account and returns a JWT token
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const auth = await client.customers.create({
            email: 'newuser@example.com',
            password: 'password123',
            password_confirmation: 'password123',
            first_name: 'John',
            last_name: 'Doe',
            phone: '+1234567890',
            accepts_email_marketing: true,
            metadata: { source: 'storefront' },
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '201':
          description: registration successful
          content:
            application/json:
              example:
                token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImVkNGE2MDhlLTdmNmUtNDc5NS1iNDc0LWU0MGQ2NGY1NjM0NCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc5MzkwNzMzfQ.zdjx-98AkEn-FCaKaIeYCOa0VzQacbTGsoD8RtSVrIc
                refresh_token: JmzdDVvP1CZnWvpsNvAwkEos
                user:
                  id: cus_UkLWZg9DAJ
                  email: newuser@example.com
                  first_name: John
                  last_name: Doe
                  phone: "+1234567890"
                  accepts_email_marketing: true
                  full_name: John Doe
                  available_store_credit_total: '0'
                  display_available_store_credit_total: "$0.00"
                  addresses: []
                  default_billing_address:
                  default_shipping_address:
              schema:
                "$ref": "#/components/schemas/AuthResponse"
        '422':
          description: email already taken
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Email has already been taken
                  details:
                    email:
                    - has already been taken
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  example: newuser@example.com
                password:
                  type: string
                  minLength: 6
                  example: password123
                password_confirmation:
                  type: string
                  example: password123
                first_name:
                  type: string
                  example: John
                last_name:
                  type: string
                  example: Doe
                phone:
                  type: string
                  example: "+1234567890"
                accepts_email_marketing:
                  type: boolean
                  example: true
                metadata:
                  type: object
                  example:
                    source: storefront
              required:
              - email
              - password
  "/api/v3/store/customers/me":
    get:
      summary: Get current customer profile
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Returns the profile of the currently authenticated customer
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const customer = await client.customer.get({
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer JWT token
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: profile found
          content:
            application/json:
              example:
                id: cus_UkLWZg9DAJ
                email: drew@skiles.ca
                first_name: Zackary
                last_name: Lind
                phone: 555-555-0199
                accepts_email_marketing: false
                full_name: Zackary Lind
                available_store_credit_total: '0'
                display_available_store_credit_total: "$0.00"
                addresses:
                - id: addr_gbHJdmfrXB
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 164 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: true
                  is_default_shipping: false
                  state_name: New York
                - id: addr_UkLWZg9DAJ
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 163 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: true
                  state_name: New York
                default_billing_address:
                  id: addr_gbHJdmfrXB
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 164 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: true
                  is_default_shipping: false
                  state_name: New York
                default_shipping_address:
                  id: addr_UkLWZg9DAJ
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 163 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: true
                  state_name: New York
              schema:
                "$ref": "#/components/schemas/Customer"
        '401':
          description: unauthorized - invalid token
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update current customer profile
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Updates the profile of the currently authenticated customer
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const customer = await client.customer.update({
            first_name: 'John',
            last_name: 'Doe',
            metadata: { preferred_contact: 'email' },
          }, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: profile updated
          content:
            application/json:
              example:
                id: cus_UkLWZg9DAJ
                email: mimi_marquardt@gibson.co.uk
                first_name: Updated
                last_name: Name
                phone: 555-555-0199
                accepts_email_marketing: false
                full_name: Updated Name
                available_store_credit_total: '0'
                display_available_store_credit_total: "$0.00"
                addresses:
                - id: addr_gbHJdmfrXB
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 166 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: true
                  is_default_shipping: false
                  state_name: New York
                - id: addr_UkLWZg9DAJ
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 165 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: true
                  state_name: New York
                default_billing_address:
                  id: addr_gbHJdmfrXB
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 166 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: true
                  is_default_shipping: false
                  state_name: New York
                default_shipping_address:
                  id: addr_UkLWZg9DAJ
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 165 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: true
                  state_name: New York
              schema:
                "$ref": "#/components/schemas/Customer"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Email can't be blank
                  details:
                    email:
                    - can't be blank
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                  example: John
                last_name:
                  type: string
                  example: Doe
                email:
                  type: string
                  format: email
                  example: customer@example.com
                password:
                  type: string
                  example: newpassword123
                password_confirmation:
                  type: string
                  example: newpassword123
                accepts_email_marketing:
                  type: boolean
                  example: true
                phone:
                  type: string
                  example: "+1 555 123 4567"
                metadata:
                  type: object
                  example:
                    preferred_contact: email
  "/api/v3/store/digitals/{token}":
    get:
      summary: Download a digital product
      tags:
      - Digitals
      description: |
        Downloads a digital product file using the digital link token.
        The token is provided via the `download_url` field on digital links
        returned with order line items. No API key or authentication required —
        the token itself grants access.
        Each download increments the access counter. Downloads may be limited by
        store settings (number of downloads and/or time-based expiration).
      parameters:
      - name: token
        in: path
        required: true
        description: Digital link token
        schema:
          type: string
      responses:
        '200':
          description: file downloaded
          content:
            application/json: {}
        '403':
          description: download link expired or limit exceeded
          content:
            application/json:
              example:
                error:
                  code: digital_link_expired
                  message: Download link expired or invalid
            application/octet-stream:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '404':
          description: digital link not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Digital link not found
            application/octet-stream:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/carts/{cart_id}/discount_codes":
    post:
      summary: Apply discount code
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: |
        Applies a promotion discount code to the cart. The code is matched case-insensitively.

        For gift cards, use the dedicated `POST /carts/{cart_id}/gift_cards` endpoint instead.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const cart = await client.carts.discountCodes.apply('cart_abc123', 'SAVE10', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        description: Bearer token for authenticated customers
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        description: Order token for guest access
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID (e.g., cart_abc123)
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: Unique key for request idempotency.
        schema:
          type: string
      responses:
        '201':
          description: discount code applied
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R983640452
                token: FUsN4w2fk57RAyQxK2uwVh1EFUSeoApoNWz
                email: jamey@weberwalter.ca
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                item_total: '10.0'
                display_item_total: "$10.00"
                adjustment_total: "-10.0"
                display_adjustment_total: "-$10.00"
                discount_total: "-10.0"
                display_discount_total: "-$10.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: '100.0'
                display_total: "$100.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '100.0'
                display_amount_due: "$100.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:
                - id: discount_UkLWZg9DAJ
                  promotion_id: promo_UkLWZg9DAJ
                  name: Promo
                  description:
                  code: save10
                  amount: "-10.0"
                  display_amount: "-$10.00"
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 868984
                  slug: product-868984
                  options_text: ''
                  price: '10.0'
                  display_price: "$10.00"
                  total: '0.0'
                  display_total: "$0.00"
                  adjustment_total: "-10.0"
                  display_adjustment_total: "-$10.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: "-10.0"
                  display_discount_total: "-$10.00"
                  pre_tax_amount: '10.0'
                  display_pre_tax_amount: "$10.00"
                  discounted_amount: '0.0'
                  display_discounted_amount: "$0.00"
                  display_compare_at_amount: "$0.00"
                  compare_at_amount:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments:
                - id: ful_UkLWZg9DAJ
                  number: H01257048332
                  tracking: U10000
                  tracking_url:
                  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:
                  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: Idell Corkery
                    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: 183 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: 184 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:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
        '422':
          description: invalid discount code
          content:
            application/json:
              example:
                error:
                  code: processing_error
                  message: The coupon code you entered doesn't exist. Please try again.
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                  example: SAVE10
                  description: Promotion discount code to apply
              required:
              - code
  "/api/v3/store/carts/{cart_id}/discount_codes/{id}":
    delete:
      summary: Remove discount code
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Removes a previously applied discount code from the cart. The ID
        is the discount code string itself.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const cart = await client.carts.discountCodes.remove('cart_abc123', 'SAVE10', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        description: Bearer token for authenticated customers
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: The discount code string to remove (e.g., SAVE10)
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        description: Order token for guest access
        schema:
          type: string
      responses:
        '200':
          description: discount code removed
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R506477402
                token: ZbbF51wzUqPGTMG3ngYRzSSDbLK3Ee9wdcW
                email: norris@wintheiser.us
                customer_note:
                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_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 883927
                  slug: product-883927
                  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:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments:
                - id: ful_UkLWZg9DAJ
                  number: H66163861804
                  tracking: U10000
                  tracking_url:
                  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:
                  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: Faye Kertzmann
                    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: 191 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: 192 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:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
        '422':
          description: discount code not found on cart
          content:
            application/json:
              example:
                error:
                  code: processing_error
                  message: The coupon code you entered doesn't exist. Please try again.
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/carts/{cart_id}/fulfillments/{id}":
    patch:
      summary: Select delivery rate for fulfillment
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Selects a delivery rate for a specific fulfillment and auto-advances
        checkout.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const cart = await client.carts.fulfillments.update('cart_abc123', 'ful_abc123', {
            selected_delivery_rate_id: 'dr_abc123',
          }, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Fulfillment ID
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        description: Order token for guest access
        schema:
          type: string
      responses:
        '200':
          description: delivery rate selected, returns updated cart
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R787693305
                token: naZG9yps6zPNYyBArZBgKKY6nnqYpGC5rTw
                email: isabelle.gutmann@batzdaugherty.com
                customer_note:
                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: 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 905832
                  slug: product-905832
                  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:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments:
                - id: ful_UkLWZg9DAJ
                  number: H48213234073
                  tracking: U10000
                  tracking_url:
                  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:
                  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: Kerri Hahn
                    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: 199 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: 200 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:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
        '404':
          description: delivery rate not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Shipping rate not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                selected_delivery_rate_id:
                  type: string
                  example: dr_abc123
                  description: Delivery rate ID to select
              required:
              - selected_delivery_rate_id
  "/api/v3/store/carts/{cart_id}/gift_cards":
    post:
      summary: Apply gift card
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: |
        Applies a gift card to the cart. Gift cards are treated as a payment method, not a discount —
        the cart `total` remains unchanged while `amount_due` is reduced.

        For promotion discount codes, use the `POST /carts/{cart_id}/discount_codes` endpoint instead.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const cart = await client.carts.giftCards.apply('cart_abc123', 'GC-ABCD-1234', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        description: Bearer token for authenticated customers
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        description: Order token for guest access
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID (e.g., cart_abc123)
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: Unique key for request idempotency.
        schema:
          type: string
      responses:
        '201':
          description: gift card applied
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R501407956
                token: mBMtKueSANaxHuT7o3H1zs5CWXfBtLZR76a
                email: aldo.hickle@bode.co.uk
                customer_note:
                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: '50.0'
                display_gift_card_total: "$50.00"
                amount_due: '60.0'
                display_amount_due: "$60.00"
                delivery_total: '100.0'
                display_delivery_total: "$100.00"
                warnings: []
                store_credit_total: '50.0'
                display_store_credit_total: "-$50.00"
                covered_by_store_credit: false
                current_step: address
                completed_steps: []
                requirements: []
                shipping_eq_billing_address: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 923228
                  slug: product-923228
                  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:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments:
                - id: ful_UkLWZg9DAJ
                  number: H63891944560
                  tracking: U10000
                  tracking_url:
                  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:
                  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: Julieann Kuhn
                    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:
                - id: py_UkLWZg9DAJ
                  payment_method_id: pm_UkLWZg9DAJ
                  response_code: 1-SC-20260521181222228580
                  number: PLBPL882
                  amount: '50.0'
                  display_amount: "$50.00"
                  status: checkout
                  source_type: store_credit
                  source_id: credit_UkLWZg9DAJ
                  source:
                    id: credit_UkLWZg9DAJ
                    amount: '50.0'
                    amount_used: '0.0'
                    amount_remaining: '50.0'
                    display_amount: "$50.00"
                    display_amount_used: "$0.00"
                    display_amount_remaining: "$50.00"
                    currency: USD
                  payment_method:
                    id: pm_UkLWZg9DAJ
                    name: Store Credit
                    description:
                    type: store_credit
                    session_required: false
                    source_required: true
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 207 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: 208 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:
                - id: pm_UkLWZg9DAJ
                  name: Store Credit
                  description:
                  type: store_credit
                  session_required: false
                  source_required: true
                gift_card:
                  id: gc_UkLWZg9DAJ
                  code: GIFTCODE1
                  status: active
                  currency: USD
                  amount: '50.0'
                  amount_used: '50.0'
                  amount_authorized: '0.0'
                  amount_remaining: '0.0'
                  display_amount: "$50.00"
                  display_amount_used: "$50.00"
                  display_amount_remaining: "$0.00"
                  expires_at:
                  redeemed_at:
                  expired: false
                  active: true
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
        '404':
          description: gift card not found
          content:
            application/json:
              example:
                error:
                  code: gift_card_not_found
                  message: The Gift Card was not found.
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '422':
          description: gift card already redeemed
          content:
            application/json:
              example:
                error:
                  code: gift_card_already_redeemed
                  message: The Gift Card has already been redeemed.
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                  example: GC-ABCD-1234
                  description: Gift card code to apply
              required:
              - code
  "/api/v3/store/carts/{cart_id}/gift_cards/{id}":
    delete:
      summary: Remove gift card
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Removes a previously applied gift card from the cart.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const cart = await client.carts.giftCards.remove('cart_abc123', 'gc_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        description: Bearer token for authenticated customers
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Gift card prefixed ID (e.g., gc_abc123)
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        description: Order token for guest access
        schema:
          type: string
      responses:
        '200':
          description: gift card removed
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R971301843
                token: TAXrAS6nE34CGB4J4SM9jYAC7D1LAfEdvuB
                email: beatris@monahanconsidine.name
                customer_note:
                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_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 966445
                  slug: product-966445
                  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:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments:
                - id: ful_UkLWZg9DAJ
                  number: H50426852278
                  tracking: U10000
                  tracking_url:
                  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:
                  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: Hilda Gorczany
                    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:
                - id: py_UkLWZg9DAJ
                  payment_method_id: pm_UkLWZg9DAJ
                  response_code: 1-SC-20260521181224917306
                  number: P50IZG86
                  amount: '50.0'
                  display_amount: "$50.00"
                  status: invalid
                  source_type: store_credit
                  source_id: credit_UkLWZg9DAJ
                  source:
                    id: credit_UkLWZg9DAJ
                    amount: '50.0'
                    amount_used: '0.0'
                    amount_remaining: '50.0'
                    display_amount: "$50.00"
                    display_amount_used: "$0.00"
                    display_amount_remaining: "$50.00"
                    currency: USD
                  payment_method:
                    id: pm_UkLWZg9DAJ
                    name: Store Credit
                    description:
                    type: store_credit
                    session_required: false
                    source_required: true
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 223 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: 224 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:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
  "/api/v3/store/customers/me/gift_cards":
    get:
      summary: List gift cards
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Returns all gift cards for the authenticated customer
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const giftCards = await client.customer.giftCards.list({}, {
            token: '<token>',
          })
      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
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: gift cards found
          content:
            application/json:
              example:
                data:
                - id: gc_UkLWZg9DAJ
                  code: DFE1B771D0A9F320
                  status: active
                  currency: USD
                  amount: '10.0'
                  amount_used: '0.0'
                  amount_authorized: '0.0'
                  amount_remaining: '10.0'
                  display_amount: "$10.00"
                  display_amount_used: "$0.00"
                  display_amount_remaining: "$10.00"
                  expires_at:
                  redeemed_at:
                  expired: false
                  active: true
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/GiftCard"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/customers/me/gift_cards/{id}":
    get:
      summary: Get a gift card
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Returns a gift card by its ID
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const giftCard = await client.customer.giftCards.get('gc_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: gift card found
          content:
            application/json:
              example:
                id: gc_UkLWZg9DAJ
                code: B3971A4B112F7143
                status: active
                currency: USD
                amount: '10.0'
                amount_used: '0.0'
                amount_authorized: '0.0'
                amount_remaining: '10.0'
                display_amount: "$10.00"
                display_amount_used: "$0.00"
                display_amount_remaining: "$10.00"
                expires_at:
                redeemed_at:
                expired: false
                active: true
              schema:
                "$ref": "#/components/schemas/GiftCard"
        '404':
          description: gift card not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Gift card not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/carts/{cart_id}/items":
    post:
      summary: Add item to cart
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Adds a variant to the cart. Creates a new line item or increases
        quantity if variant already in cart.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const cart = await client.carts.items.create('cart_abc123', {
            variant_id: 'variant_abc123',
            quantity: 2,
          }, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        description: Bearer token for authenticated customers
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        description: Order token for guest access
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID (e.g., cart_abc123)
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: Unique key for request idempotency.
        schema:
          type: string
      responses:
        '201':
          description: item added with metadata
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R881799706
                token: RVbjRddtDRtcExjXQRpMB8Bim5LNSShGBH6
                email: remona@effertzbauch.info
                customer_note:
                currency: USD
                locale: en
                total_quantity: 2
                item_total: '29.99'
                display_item_total: "$29.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: '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: address
                  field: ship_address
                  message: Shipping address is required
                - step: delivery
                  field: shipping_method
                  message: Select a shipping method for all shipments
                - 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 996441
                  slug: product-996441
                  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:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                - id: li_gbHJdmfrXB
                  variant_id: variant_gbHJdmfrXB
                  quantity: 1
                  currency: USD
                  name: Product 1009810
                  slug: product-1009810
                  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'
                  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: '19.99'
                  display_pre_tax_amount: "$19.99"
                  discounted_amount: '19.99'
                  display_discounted_amount: "$19.99"
                  display_compare_at_amount: "$0.00"
                  compare_at_amount:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments: []
                payments: []
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 238 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:
                payment_methods: []
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
        '404':
          description: variant not found
          content:
            application/json:
              example:
                error:
                  code: variant_not_found
                  message: Variant not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                variant_id:
                  type: string
                  example: variant_abc123
                  description: Variant ID to add
                quantity:
                  type: integer
                  example: 2
                  description: 'Quantity to add (default: 1)'
                metadata:
                  type: object
                  additionalProperties: true
                  description: Arbitrary key-value metadata
                  example:
                    gift_message: Happy Birthday!
              required:
              - variant_id
  "/api/v3/store/carts/{cart_id}/items/{id}":
    patch:
      summary: Update line item quantity
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Updates the quantity of a line item in the cart
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const cart = await client.carts.items.update('cart_abc123', 'li_abc123', {
            quantity: 5,
          }, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Line item ID
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: metadata updated on line item
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R794423726
                token: 1sJMUmLYsh3UaeGjL4VQKgK3DMj8h2YAx2z
                email: pablo_corwin@hillsstark.biz
                customer_note:
                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: 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: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 1039114
                  slug: product-1039114
                  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:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments: []
                payments: []
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 247 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:
                payment_methods: []
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                quantity:
                  type: integer
                  minimum: 1
                  example: 5
                metadata:
                  type: object
                  additionalProperties: true
                  description: Arbitrary key-value metadata (merged with existing)
                  example:
                    engraving: J.D.
    delete:
      summary: Remove line item from cart
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Removes a line item from the cart
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const cart = await client.carts.items.delete('cart_abc123', 'li_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: line item removed, returns updated cart
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R184817343
                token: vPBcAwTjPCjFLRYvznh9D9dkaWZt8aapnyH
                email: michael.lang@hackett.com
                customer_note:
                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: ship_address
                  message: Shipping address is required
                - 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_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 250 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:
                payment_methods: []
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
        '404':
          description: line item not found
          content:
            application/json:
              example:
                error:
                  code: line_item_not_found
                  message: Line item not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/locales":
    get:
      summary: List supported locales
      tags:
      - Markets
      security:
      - api_key: []
      description: Returns locales supported by the store (derived from markets)
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const locales = await client.locales.list()
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: locales found
          content:
            application/json:
              example:
                data:
                - code: de
                  name: de
                - code: en
                  name: English (US)
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Locale"
                required:
                - data
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: Valid API key required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/markets":
    get:
      summary: List markets
      tags:
      - Markets
      security:
      - api_key: []
      description: Returns all markets for the current store with their countries,
        currency, locales, and tax configuration.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const markets = await client.markets.list()
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: markets found
          content:
            application/json:
              example:
                data:
                - id: mkt_UkLWZg9DAJ
                  name: North America
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  supported_locales:
                  - en
                  - es
                  countries:
                  - iso: US
                    iso3: USA
                    name: United States of America
                    states_required: true
                    zipcode_required: true
                - id: mkt_gbHJdmfrXB
                  name: Europe
                  currency: EUR
                  default_locale: de
                  tax_inclusive: true
                  default: false
                  supported_locales:
                  - de
                  - en
                  - fr
                  countries:
                  - iso: DE
                    iso3: IS66
                    name: Germany
                    states_required: false
                    zipcode_required: true
                  - iso: FR
                    iso3: IS67
                    name: France
                    states_required: false
                    zipcode_required: true
              schema:
                type: object
                properties:
                  data:
                    type: array
                required:
                - data
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: Valid API key required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/markets/{id}":
    get:
      summary: Get a market
      tags:
      - Markets
      security:
      - api_key: []
      description: Returns a single market by prefixed ID with its countries, currency,
        locales, and tax configuration.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const market = await client.markets.get('mkt_xxx')
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Market prefixed ID (e.g., "mkt_k5nR8xLq")
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: market found
          content:
            application/json:
              example:
                id: mkt_gbHJdmfrXB
                name: Europe
                currency: EUR
                default_locale: de
                tax_inclusive: true
                default: false
                supported_locales:
                - de
                - en
                - fr
                countries:
                - iso: DE
                  iso3: IS70
                  name: Germany
                  states_required: false
                  zipcode_required: true
                - iso: FR
                  iso3: IS71
                  name: France
                  states_required: false
                  zipcode_required: true
              schema:
                type: object
        '404':
          description: market not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Market not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/markets/resolve":
    get:
      summary: Resolve market by country
      tags:
      - Markets
      security:
      - api_key: []
      description: Determine which market applies for a given country ISO code. Useful
        for auto-selecting the correct currency and locale when a customer's location
        is known.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const market = await client.markets.resolve('DE')
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: country
        in: query
        required: true
        description: Country ISO 3166-1 alpha-2 code (e.g., "DE", "US")
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: market resolved
          content:
            application/json:
              example:
                id: mkt_gbHJdmfrXB
                name: Europe
                currency: EUR
                default_locale: de
                tax_inclusive: true
                default: false
                supported_locales:
                - de
                - en
                - fr
                countries:
                - iso: DE
                  iso3: IS74
                  name: Germany
                  states_required: false
                  zipcode_required: true
                - iso: FR
                  iso3: IS75
                  name: France
                  states_required: false
                  zipcode_required: true
              schema:
                type: object
        '404':
          description: no market for country
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Country not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/markets/{market_id}/countries":
    get:
      summary: List countries in a market
      tags:
      - Markets
      security:
      - api_key: []
      description: Returns countries belonging to a specific market. Use this for
        address form country dropdowns during checkout.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const countries = await client.markets.countries.list('mkt_xxx')
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: market_id
        in: path
        required: true
        description: Market prefixed ID
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: countries found
          content:
            application/json:
              example:
                data:
                - iso: FR
                  iso3: IS79
                  name: France
                  states_required: false
                  zipcode_required: true
                - iso: DE
                  iso3: IS78
                  name: Germany
                  states_required: false
                  zipcode_required: true
              schema:
                type: object
                properties:
                  data:
                    type: array
                required:
                - data
  "/api/v3/store/markets/{market_id}/countries/{id}":
    get:
      summary: Get a country in a market
      tags:
      - Markets
      security:
      - api_key: []
      description: Returns a single country by ISO code within a market. Supports
        ?expand=states for address forms.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const country = await client.markets.countries.get('mkt_xxx', 'DE')
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: market_id
        in: path
        required: true
        description: Market prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Country ISO 3166-1 alpha-2 code (e.g., "DE")
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: country found
          content:
            application/json:
              example:
                iso: US
                iso3: USA
                name: United States of America
                states_required: true
                zipcode_required: true
              schema:
                type: object
        '404':
          description: country not in market
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Country not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/newsletter_subscribers":
    post:
      summary: Subscribe to the newsletter
      tags:
      - Newsletter Subscribers
      security:
      - api_key: []
      description: |
        Subscribes an email address to the newsletter for the current store.

        Behavior:

        - If the email is already verified for this store, the existing subscription is returned unchanged.
        - If the request is unauthenticated (guest), the subscription is created in an unverified state
          and two events are published: `newsletter_subscriber.subscription_requested` (carrying the
          `verification_token` and the validated `redirect_url`, intended for headless storefronts that
          want to send the confirmation email themselves via a webhook handler) and the legacy
          `newsletter_subscriber.subscribed` lifecycle event (which the bundled `spree_emails` package
          listens to and uses to send a default confirmation email). The confirmation link should point
          at `redirect_url?token=<verification_token>` and call `POST /newsletter_subscribers/verify`
          when the user clicks it.
        - If the request is authenticated via JWT and the customer's email matches the subscribed email,
          the subscription is auto-verified and no events are fired — the JWT already proves email
          ownership, so no confirmation email is needed.

        The optional `redirect_url` is where the verification token should land on the storefront. The
        server does not return a validation error when the URL is outside the store's
        [Allowed Origins](/developer/core-concepts/allowed-origins); instead, the URL is silently
        omitted from the webhook payload (secure-by-default). When no allow-list is configured on the
        store, the URL is also omitted. Callers therefore receive the same 201 regardless, and the
        webhook handler should fall back to the store's storefront URL when `redirect_url` is missing
        from the payload.

        Newsletter consent is preserved across registration: if a guest subscribes and later registers
        with the same email, the existing subscriber record is reused.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const subscriber = await client.newsletterSubscribers.create({
            email: 'subscriber@example.com',
            // Where the verification token should land. Must be in the store's
            // allowed origins. The storefront's webhook handler will send the
            // confirmation email with a link to `<redirect_url>?token=<token>`.
            redirect_url: 'https://your-store.com/newsletter/confirm',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        description: Optional Bearer JWT — when present, links the subscription to
          that customer
        schema:
          type: string
      responses:
        '201':
          description: auto-verified when JWT matches subscribed email
          content:
            application/json:
              example:
                id: sub_UkLWZg9DAJ
                email: eufemia@stoltenbergwalter.ca
                created_at: '2026-05-21T18:12:32.551Z'
                updated_at: '2026-05-21T18:12:32.553Z'
                verified: true
                verified_at: '2026-05-21T18:12:32Z'
                customer_id: cus_UkLWZg9DAJ
              schema:
                "$ref": "#/components/schemas/NewsletterSubscriber"
        '422':
          description: invalid email format
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Email is invalid
                  details:
                    email:
                    - is invalid
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  example: subscriber@example.com
                redirect_url:
                  type: string
                  format: uri
                  example: https://your-store.com/newsletter/confirm
                  description: Storefront URL the verification token should be appended
                    to. Silently omitted from the webhook payload when the store has
                    allowed origins configured and this URL does not match one of
                    them, or when no allowed origins are configured at all.
              required:
              - email
  "/api/v3/store/newsletter_subscribers/verify":
    post:
      summary: Verify a newsletter subscription
      tags:
      - Newsletter Subscribers
      security:
      - api_key: []
      description: |
        Confirms a pending newsletter subscription using the verification token sent by email.

        After successful verification:
        - The subscriber record is marked verified.
        - If the subscription is associated with a customer, that customer's `accepts_email_marketing`
          flag is set to `true`.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const subscriber = await client.newsletterSubscribers.verify({
            token: 'abc123def456',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: subscription verified
          content:
            application/json:
              example:
                id: sub_UkLWZg9DAJ
                email: pending@example.com
                created_at: '2026-05-21T18:12:32.578Z'
                updated_at: '2026-05-21T18:12:32.591Z'
                verified: true
                verified_at: '2026-05-21T18:12:32Z'
                customer_id:
              schema:
                "$ref": "#/components/schemas/NewsletterSubscriber"
        '422':
          description: missing token
          content:
            application/json:
              example:
                error:
                  code: parameter_missing
                  message: token is required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                  example: abc123def456
                  description: Verification token from the confirmation email
              required:
              - token
  "/api/v3/store/orders/{id}":
    get:
      summary: Get an order
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: Returns a single completed order by prefixed ID. Accessible via
        JWT (authenticated users) or order token header (guests).
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const order = await client.orders.get('or_abc123', {}, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        description: Bearer token for authenticated customers
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        description: Order token for guest access
        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). 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: order found (guest via order token)
          content:
            application/json:
              example:
                id: or_UkLWZg9DAJ
                market_id:
                channel_id: ch_UkLWZg9DAJ
                number: R444420762
                email: guest@example.com
                customer_note:
                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"
                fulfillment_status:
                payment_status:
                completed_at: '2026-05-21T18:12:33.331Z'
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 1079404
                  slug: product-1079404
                  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:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments:
                - id: ful_UkLWZg9DAJ
                  number: H37244671113
                  tracking: U10000
                  tracking_url:
                  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:
                  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: Bud Bartoletti
                    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_UkLWZg9DAJ
                    name: UPS Ground
                    selected: true
                    cost: '10.0'
                    total: '10.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    display_cost: "$10.00"
                    display_total: "$10.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_UkLWZg9DAJ
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 260 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: 261 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
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Order"
        '404':
          description: incomplete order not accessible
          content:
            application/json:
              example:
                error:
                  code: order_not_found
                  message: Order not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/carts/{cart_id}/payment_sessions":
    post:
      summary: Create payment session
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Creates a new payment session for the cart. Delegates to the payment
        gateway to initialize a provider-specific session (e.g. Stripe PaymentIntent,
        Adyen session, PayPal order).
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const session = await client.carts.paymentSessions.create('cart_abc123', {
            payment_method_id: 'pm_abc123',
          }, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        description: Bearer token for authenticated customers
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID (e.g., cart_abc123)
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        description: Order token for guest access
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: Unique key for request idempotency.
        schema:
          type: string
      responses:
        '201':
          description: payment session created
          content:
            application/json:
              example:
                id: ps_gbHJdmfrXB
                status: pending
                currency: USD
                external_id: bogus_799f9d0cdd2a024b44a972f2
                external_data:
                  client_secret: bogus_secret_e705380ff182660e
                customer_external_id:
                expires_at:
                amount: '110.0'
                payment_method_id: pm_UkLWZg9DAJ
                order_id: or_UkLWZg9DAJ
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Credit Card
                  description:
                  type: bogus
                  session_required: true
                  source_required: true
              schema:
                "$ref": "#/components/schemas/PaymentSession"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                payment_method_id:
                  type: string
                  example: pm_abc123
                  description: Payment method ID
                amount:
                  type: string
                  example: '99.99'
                  description: Payment amount (defaults to order total minus store
                    credits)
                external_data:
                  type: object
                  description: Provider-specific data passed to the gateway
              required:
              - payment_method_id
  "/api/v3/store/carts/{cart_id}/payment_sessions/{id}":
    parameters:
    - name: x-spree-api-key
      in: header
      required: true
      schema:
        type: string
    - name: Authorization
      in: header
      required: false
      description: Bearer token for authenticated customers
      schema:
        type: string
    - name: cart_id
      in: path
      required: true
      description: Cart prefixed ID
      schema:
        type: string
    - name: id
      in: path
      required: true
      description: Payment session ID
      schema:
        type: string
    - name: x-spree-token
      in: header
      required: false
      description: Order token for guest access
      schema:
        type: string
    get:
      summary: Get payment session
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Returns a single payment session with its current status and provider
        data.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const session = await client.carts.paymentSessions.get('cart_abc123', 'ps_abc123', {
            token: '<token>',
          })
      responses:
        '200':
          description: payment session found
          content:
            application/json:
              example:
                id: ps_UkLWZg9DAJ
                status: pending
                currency: USD
                external_id: bogus_aecf7276c91c09ca9e9ec79a
                external_data:
                  client_secret: secret_123
                customer_external_id:
                expires_at:
                amount: '110.0'
                payment_method_id: pm_UkLWZg9DAJ
                order_id: or_UkLWZg9DAJ
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Credit Card
                  description:
                  type: bogus
                  session_required: true
                  source_required: true
              schema:
                "$ref": "#/components/schemas/PaymentSession"
        '404':
          description: payment session not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Payment session not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update payment session
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Updates a payment session. Delegates to the payment gateway to
        sync changes with the provider.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const session = await client.carts.paymentSessions.update('cart_abc123', 'ps_abc123', {
            amount: '50.00',
          }, {
            token: '<token>',
          })
      parameters: []
      responses:
        '200':
          description: payment session updated
          content:
            application/json:
              example:
                id: ps_UkLWZg9DAJ
                status: pending
                currency: USD
                external_id: bogus_4d892ef9777434a81f39f60d
                external_data:
                  client_secret: secret_123
                customer_external_id:
                expires_at:
                amount: '50.0'
                payment_method_id: pm_UkLWZg9DAJ
                order_id: or_UkLWZg9DAJ
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Credit Card
                  description:
                  type: bogus
                  session_required: true
                  source_required: true
              schema:
                "$ref": "#/components/schemas/PaymentSession"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: string
                  example: '50.00'
                  description: Updated payment amount
                external_data:
                  type: object
                  description: Provider-specific data to update
  "/api/v3/store/carts/{cart_id}/payment_sessions/{id}/complete":
    parameters:
    - name: x-spree-api-key
      in: header
      required: true
      schema:
        type: string
    - name: Authorization
      in: header
      required: false
      description: Bearer token for authenticated customers
      schema:
        type: string
    - name: cart_id
      in: path
      required: true
      description: Cart prefixed ID
      schema:
        type: string
    - name: id
      in: path
      required: true
      description: Payment session ID
      schema:
        type: string
    - name: x-spree-token
      in: header
      required: false
      description: Order token for guest access
      schema:
        type: string
    patch:
      summary: Complete payment session
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Completes a payment session by confirming the payment with the
        provider. This triggers payment capture/authorization and order completion.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const session = await client.carts.paymentSessions.complete('cart_abc123', 'ps_abc123', {
            session_result: 'success',
          }, {
            token: '<token>',
          })
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Unique key for request idempotency.
        schema:
          type: string
      responses:
        '200':
          description: payment session completed
          content:
            application/json:
              example:
                id: ps_UkLWZg9DAJ
                status: completed
                currency: USD
                external_id: bogus_a8a35246fb9e9da3d0a251b8
                external_data:
                  client_secret: secret_123
                customer_external_id:
                expires_at:
                amount: '110.0'
                payment_method_id: pm_UkLWZg9DAJ
                order_id: or_UkLWZg9DAJ
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Credit Card
                  description:
                  type: bogus
                  session_required: true
                  source_required: true
              schema:
                "$ref": "#/components/schemas/PaymentSession"
        '404':
          description: payment session not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Payment session not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                session_result:
                  type: string
                  description: Provider-specific session result token
                external_data:
                  type: object
                  description: Provider-specific completion data
  "/api/v3/store/customers/me/payment_setup_sessions":
    post:
      summary: Create payment setup session
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Creates a new payment setup session for saving a payment method
        for future use. Delegates to the payment gateway to initialize a provider-specific
        setup flow (e.g. Stripe SetupIntent, Adyen zero-auth tokenization).
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const session = await client.customer.paymentSetupSessions.create({
            payment_method_id: 'pm_abc123',
          }, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '201':
          description: payment setup session created
          content:
            application/json:
              example:
                id: pss_gbHJdmfrXB
                status: pending
                external_id: bogus_seti_c85316f2ab8114ec81687ed4
                external_client_secret: bogus_seti_secret_a15e9cd71178a98c
                external_data: {}
                payment_method_id: pm_UkLWZg9DAJ
                payment_source_id:
                payment_source_type:
                customer_id: cus_UkLWZg9DAJ
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Credit Card
                  description:
                  type: bogus
                  session_required: true
                  source_required: true
              schema:
                "$ref": "#/components/schemas/PaymentSetupSession"
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '404':
          description: payment method not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Payment method not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                payment_method_id:
                  type: string
                  example: pm_abc123
                  description: Payment method ID
                external_data:
                  type: object
                  description: Provider-specific data passed to the gateway
              required:
              - payment_method_id
  "/api/v3/store/customers/me/payment_setup_sessions/{id}":
    parameters:
    - name: x-spree-api-key
      in: header
      required: true
      schema:
        type: string
    - name: Authorization
      in: header
      required: true
      schema:
        type: string
    - name: id
      in: path
      required: true
      description: Payment setup session ID
      schema:
        type: string
    get:
      summary: Get payment setup session
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Returns a payment setup session with its current status and provider
        data.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const session = await client.customer.paymentSetupSessions.get('pss_abc123', {
            token: '<token>',
          })
      responses:
        '200':
          description: payment setup session found
          content:
            application/json:
              example:
                id: pss_UkLWZg9DAJ
                status: pending
                external_id: seti_test_674107c9a4a65317bbdc129d
                external_client_secret: seti_secret_66eb1d151fa172598a741e14
                external_data:
                  client_secret: secret_123
                payment_method_id: pm_UkLWZg9DAJ
                payment_source_id:
                payment_source_type:
                customer_id: cus_UkLWZg9DAJ
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Credit Card
                  description:
                  type: bogus
                  session_required: true
                  source_required: true
              schema:
                "$ref": "#/components/schemas/PaymentSetupSession"
        '404':
          description: payment setup session not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Payment setup session not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/customers/me/payment_setup_sessions/{id}/complete":
    parameters:
    - name: x-spree-api-key
      in: header
      required: true
      schema:
        type: string
    - name: Authorization
      in: header
      required: true
      schema:
        type: string
    - name: id
      in: path
      required: true
      description: Payment setup session ID
      schema:
        type: string
    patch:
      summary: Complete payment setup session
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Completes a payment setup session by confirming the setup with
        the provider, resulting in a saved payment method.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const session = await client.customer.paymentSetupSessions.complete('pss_abc123', {}, {
            token: '<token>',
          })
      parameters: []
      responses:
        '200':
          description: payment setup session completed
          content:
            application/json:
              example:
                id: pss_UkLWZg9DAJ
                status: completed
                external_id: seti_test_047d39fe078d8f5dfb59fc7a
                external_client_secret: seti_secret_8320035d2ef40c47c4e63f5b
                external_data:
                  client_secret: secret_123
                payment_method_id: pm_UkLWZg9DAJ
                payment_source_id: card_UkLWZg9DAJ
                payment_source_type: Spree::CreditCard
                customer_id: cus_UkLWZg9DAJ
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Credit Card
                  description:
                  type: bogus
                  session_required: true
                  source_required: true
              schema:
                "$ref": "#/components/schemas/PaymentSetupSession"
        '404':
          description: payment setup session not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Payment setup session not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                external_data:
                  type: object
                  description: Provider-specific completion data
  "/api/v3/store/carts/{cart_id}/payments":
    post:
      summary: Create payment
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Creates a payment for a non-session payment method (e.g. Check,
        Cash on Delivery, Bank Transfer). For payment methods that require a session
        (e.g. Stripe, PayPal), use the payment sessions endpoint instead.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const payment = await client.carts.payments.create('cart_abc123', {
            payment_method_id: 'pm_abc123',
          }, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        description: Order token for guest access
        schema:
          type: string
      responses:
        '201':
          description: payment created
          content:
            application/json:
              example:
                id: py_UkLWZg9DAJ
                payment_method_id: pm_UkLWZg9DAJ
                response_code:
                number: PDW8QZGM
                amount: '110.0'
                display_amount: "$110.00"
                status: checkout
                source_type:
                source_id:
                source:
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Check
                  description:
                  type: check
                  session_required: false
                  source_required: false
              schema:
                "$ref": "#/components/schemas/Payment"
        '422':
          description: session-based payment method
          content:
            application/json:
              example:
                error:
                  code: payment_session_required
                  message: This payment method requires a payment session. Use the
                    payment sessions endpoint instead.
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                payment_method_id:
                  type: string
                  example: pm_abc123
                  description: Payment method ID (must be a non-session payment method)
                amount:
                  type: string
                  example: '99.99'
                  description: Payment amount (defaults to order total minus store
                    credits)
                metadata:
                  type: object
                  description: Arbitrary metadata to attach to the payment
              required:
              - payment_method_id
  "/api/v3/store/policies":
    get:
      summary: List store policies
      tags:
      - Policies
      security:
      - api_key: []
      description: |
        Returns all policies for the current store (e.g., return policy, privacy policy, terms of service).
        Policies are managed in Spree Admin and contain rich text content.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const policies = await client.policies.list()
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: policies listed
          content:
            application/json:
              example:
                data:
                - id: pol_gbHJdmfrXB
                  name: Privacy Policy
                  slug: privacy-policy
                  body: ''
                  body_html: ''
                - id: pol_OIJLhNcSbf
                  name: Privacy Policy
                  slug: privacy-policy-64c6fe11-a85d-4ac3-bcf3-2d7e2f51e471
                  body: We respect your privacy.
                  body_html: |
                    <div class="trix-content">
                      We respect your privacy.
                    </div>
                - id: pol_uw2YK1rnl0
                  name: Return Policy
                  slug: return-policy
                  body: You can return items within 30 days.
                  body_html: |
                    <div class="trix-content">
                      You can return items within 30 days.
                    </div>
                - id: pol_EfhxLZ9ck8
                  name: Returns Policy
                  slug: returns-policy
                  body: ''
                  body_html: ''
                - id: pol_VqXmZF31wY
                  name: Shipping Policy
                  slug: shipping-policy
                  body: ''
                  body_html: ''
                - id: pol_UkLWZg9DAJ
                  name: Terms of Service
                  slug: terms-of-service
                  body: ''
                  body_html: ''
                meta:
                  page: 1
                  limit: 25
                  count: 6
                  pages: 1
                  from: 1
                  to: 6
                  in: 6
                  previous:
                  next:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Policy"
                required:
                - data
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: Valid API key required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/policies/{id}":
    get:
      summary: Get a policy
      tags:
      - Policies
      security:
      - api_key: []
      description: Returns a single policy by slug or prefixed ID. Includes the full
        rich text body.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const policy = await client.policies.get('return-policy')
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Policy slug (e.g., return-policy) or prefixed ID (e.g., pol_abc123)
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include. id is always included.
        schema:
          type: string
      responses:
        '200':
          description: policy found
          content:
            application/json:
              example:
                id: pol_uw2YK1rnl0
                name: Return Policy
                slug: return-policy
                body: You can return items within 30 days.
                body_html: |
                  <div class="trix-content">
                    You can return items within 30 days.
                  </div>
              schema:
                "$ref": "#/components/schemas/Policy"
        '404':
          description: policy not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Policy not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/products":
    get:
      summary: List products
      tags:
      - Product Catalog
      security:
      - api_key: []
      description: Returns a paginated list of active products for the current store
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const products = await client.products.list({
            page: 1,
            limit: 25,
            sort: 'price',
            name_cont: 'shirt',
            price_gte: 20,
            price_lte: 100,
            with_option_value_ids: ['optval_abc', 'optval_def'],
            expand: ['variants', 'media'],
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        description: Publishable API key
        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 items per page (default: 25, max: 100)'
        schema:
          type: integer
      - name: sort
        in: query
        required: false
        description: 'Sort order. Prefix with - for descending. Values: price, -price,
          best_selling, name, -name, -available_on, available_on'
        schema:
          type: string
      - name: q[name_cont]
        in: query
        required: false
        description: Filter by name containing string
        schema:
          type: string
      - name: q[in_category]
        in: query
        required: false
        description: Filter by category prefixed ID (includes descendants)
        schema:
          type: string
      - name: q[in_categories][]
        in: query
        required: false
        description: Filter by multiple category prefixed IDs (OR logic, includes
          descendants)
        schema:
          type: string
      - name: q[price_gte]
        in: query
        required: false
        description: Filter by minimum price
        schema:
          type: number
      - name: q[price_lte]
        in: query
        required: false
        description: Filter by maximum price
        schema:
          type: number
      - name: q[with_option_value_ids][]
        in: query
        required: false
        description: Filter by option value prefix IDs (e.g., optval_abc). Pass multiple
          values for OR logic.
        schema:
          type: string
      - name: q[in_stock]
        in: query
        required: false
        description: Filter to only in-stock products
        schema:
          type: boolean
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (variants, media, categories,
          option_types)
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: products found
          content:
            application/json:
              example:
                data:
                - id: prod_UkLWZg9DAJ
                  name: Product 117952
                  slug: product-117952
                  meta_title:
                  meta_description:
                  meta_keywords:
                  variant_count: 1
                  available_on: '2025-05-21T18:12:43.946Z'
                  purchasable: true
                  in_stock: false
                  backorderable: true
                  available: true
                  description: A comfortable cotton t-shirt.
                  description_html: "<p>A <strong>comfortable</strong> cotton t-shirt.</p>"
                  default_variant_id: variant_gbHJdmfrXB
                  thumbnail_url:
                  tags: []
                  price:
                    id: price_gbHJdmfrXB
                    amount: '19.99'
                    amount_in_cents: 1999
                    compare_at_amount:
                    compare_at_amount_in_cents:
                    currency: USD
                    display_amount: "$19.99"
                    display_compare_at_amount:
                    price_list_id:
                  original_price:
                - id: prod_gbHJdmfrXB
                  name: Product 1184416
                  slug: product-1184416
                  meta_title:
                  meta_description:
                  meta_keywords:
                  variant_count: 0
                  available_on: '2025-05-21T18:12:44.008Z'
                  purchasable: true
                  in_stock: false
                  backorderable: true
                  available: true
                  description: Impedit quam aliquid ducimus magni. Quas nulla placeat
                    totam suscipit doloribus quos inventore earum. Veniam officiis
                    ad ipsum sed optio error perferendis. Doloremque molestias magnam
                    harum consequatur at accusamus tempore sunt. Deleniti voluptatum
                    laborum vero nisi. Sunt delectus soluta amet hic consequuntur
                    occaecati. Molestias illum minima velit ullam. Modi animi temporibus
                    adipisci veritatis voluptatum libero unde. Sunt mollitia tenetur
                    fugit enim. Accusantium minima id culpa laudantium molestias.
                    Rerum saepe necessitatibus repellat tempora quis. Unde saepe laborum
                    iure non quisquam nesciunt sed. Voluptas debitis placeat asperiores
                    dolorem quia facilis rem. Atque quae enim at quis accusamus sequi
                    vel.
                  description_html: |-
                    Impedit quam aliquid ducimus magni. Quas nulla placeat totam suscipit doloribus quos inventore earum. Veniam officiis ad ipsum sed optio error perferendis.
                    Doloremque molestias magnam harum consequatur at accusamus tempore sunt. Deleniti voluptatum laborum vero nisi. Sunt delectus soluta amet hic consequuntur occaecati.
                    Molestias illum minima velit ullam. Modi animi temporibus adipisci veritatis voluptatum libero unde. Sunt mollitia tenetur fugit enim. Accusantium minima id culpa laudantium molestias.
                    Rerum saepe necessitatibus repellat tempora quis. Unde saepe laborum iure non quisquam nesciunt sed. Voluptas debitis placeat asperiores dolorem quia facilis rem. Atque quae enim at quis accusamus sequi vel.
                  default_variant_id: variant_EfhxLZ9ck8
                  thumbnail_url:
                  tags: []
                  price:
                    id: price_EfhxLZ9ck8
                    amount: '19.99'
                    amount_in_cents: 1999
                    compare_at_amount:
                    compare_at_amount_in_cents:
                    currency: USD
                    display_amount: "$19.99"
                    display_compare_at_amount:
                    price_list_id:
                  original_price:
                meta:
                  page: 1
                  limit: 25
                  count: 2
                  pages: 1
                  from: 1
                  to: 2
                  in: 2
                  previous:
                  next:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Product"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
        '401':
          description: unauthorized - invalid or missing API key
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: Valid API key required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/products/{id}":
    get:
      summary: Get a product
      tags:
      - Product Catalog
      security:
      - api_key: []
      description: Returns a single product by slug or prefix ID
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const product = await client.products.get('spree-tote', {
            expand: ['variants', 'media'],
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        description: Publishable API key
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Product slug (e.g., spree-tote) or prefix ID (e.g., product_abc123)
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: product without prior_price expanded does not include field
          content:
            application/json:
              example:
                id: prod_UkLWZg9DAJ
                name: Product 1453321
                slug: product-1453321
                meta_title:
                meta_description:
                meta_keywords:
                variant_count: 1
                available_on: '2025-05-21T18:12:45.816Z'
                purchasable: true
                in_stock: false
                backorderable: true
                available: true
                description: A comfortable cotton t-shirt.
                description_html: "<p>A <strong>comfortable</strong> cotton t-shirt.</p>"
                default_variant_id: variant_gbHJdmfrXB
                thumbnail_url:
                tags: []
                price:
                  id: price_gbHJdmfrXB
                  amount: '19.99'
                  amount_in_cents: 1999
                  compare_at_amount:
                  compare_at_amount_in_cents:
                  currency: USD
                  display_amount: "$19.99"
                  display_compare_at_amount:
                  price_list_id:
                original_price:
                prior_price:
                  id: _AXs1igzRC6
                  amount: '9.99'
                  amount_in_cents: 999
                  currency: USD
                  display_amount: "$9.99"
                  recorded_at: '2026-05-06T18:12:45Z'
              schema:
                "$ref": "#/components/schemas/Product"
        '404':
          description: draft product not visible
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Product not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/products/filters":
    get:
      summary: Get product filters
      tags:
      - Product Catalog
      security:
      - api_key: []
      description: |
        Returns available filters for products with their options and counts.
        Use this endpoint to build filter UIs for product listing pages.

        The filters are context-aware - when a category_id is provided, only filters
        relevant to products in that category are returned.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const filters = await client.products.filters({
            category_id: 'ctg_abc123',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        description: Publishable API key
        schema:
          type: string
      - name: category_id
        in: query
        required: false
        description: Scope filters to products in this category (prefix ID)
        schema:
          type: string
      - name: q[name_cont]
        in: query
        required: false
        description: Filter by name containing string
        schema:
          type: string
      responses:
        '200':
          description: filters scoped to category
          content:
            application/json:
              example:
                filters:
                - id: price
                  type: price_range
                  min: 19.99
                  max: 19.99
                  currency: USD
                - id: availability
                  type: availability
                  options:
                  - id: in_stock
                    count: 2
                  - id: out_of_stock
                    count: 0
                - id: opt_UkLWZg9DAJ
                  type: option
                  name: size
                  label: Size
                  kind: dropdown
                  options:
                  - id: optval_UkLWZg9DAJ
                    name: small
                    label: S
                    position: 1
                    color_code:
                    image_url:
                    count: 1
                - id: categories
                  type: category
                  options:
                  - id: ctg_EfhxLZ9ck8
                    name: Shirts
                    permalink: taxonomy-25/taxon-32/shirts
                    count: 2
                sort_options:
                - id: manual
                - id: best_selling
                - id: price
                - id: "-price"
                - id: "-available_on"
                - id: available_on
                - id: name
                - id: "-name"
                default_sort: manual
                total_count: 2
              schema:
                type: object
                properties:
                  filters:
                    type: array
                    description: Available filters (price_range, availability, option,
                      category)
                    items:
                      type: object
                  sort_options:
                    type: array
                    description: Available sort options
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                      required:
                      - id
                  default_sort:
                    type: string
                    description: Default sort option ID
                  total_count:
                    type: integer
                    description: Total products matching current filters
                required:
                - filters
                - sort_options
                - default_sort
                - total_count
        '401':
          description: unauthorized - invalid or missing API key
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: Valid API key required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/customers/me/store_credits":
    get:
      summary: List store credits
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Returns store credits for the authenticated customer, filtered
        by current store and currency. Supports Ransack filtering.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const credits = await client.customer.storeCredits.list({}, {
            token: '<token>',
          })
      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
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., amount,currency).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: store credits found
          content:
            application/json:
              example:
                data:
                - id: credit_UkLWZg9DAJ
                  amount: '100.0'
                  amount_used: '0.0'
                  amount_remaining: '100.0'
                  display_amount: "$100.00"
                  display_amount_used: "$0.00"
                  display_amount_remaining: "$100.00"
                  currency: USD
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/StoreCredit"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/customers/me/store_credits/{id}":
    get:
      summary: Get a store credit
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const credit = await client.customer.storeCredits.get('credit_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., amount,currency).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: store credit found
          content:
            application/json:
              example:
                id: credit_UkLWZg9DAJ
                amount: '100.0'
                amount_used: '0.0'
                amount_remaining: '100.0'
                display_amount: "$100.00"
                display_amount_used: "$0.00"
                display_amount_remaining: "$100.00"
                currency: USD
              schema:
                "$ref": "#/components/schemas/StoreCredit"
        '404':
          description: store credit not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Store credit not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/carts/{cart_id}/store_credits":
    post:
      summary: Apply store credit
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Applies store credit to the cart during checkout.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const cart = await client.carts.storeCredits.apply('cart_abc123', 10.0, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID (e.g., cart_abc123)
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: Unique key for request idempotency.
        schema:
          type: string
      responses:
        '200':
          description: store credit applied
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R563436707
                token: MEKMkDqDZiwtriHVLkLzxZ7hGj4nxCtmBig
                email: renate_tromp@adams.biz
                customer_note:
                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: '100.0'
                display_amount_due: "$100.00"
                delivery_total: '100.0'
                display_delivery_total: "$100.00"
                warnings: []
                store_credit_total: '10.0'
                display_store_credit_total: "-$10.00"
                covered_by_store_credit: false
                current_step: address
                completed_steps: []
                requirements: []
                shipping_eq_billing_address: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 1657
                  slug: product-1657
                  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:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments:
                - id: ful_UkLWZg9DAJ
                  number: H22654230230
                  tracking: U10000
                  tracking_url:
                  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:
                  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: Marissa Sipes
                    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:
                - id: py_UkLWZg9DAJ
                  payment_method_id: pm_UkLWZg9DAJ
                  response_code: 1-SC-20260521181251050531
                  number: PFR3QR4H
                  amount: '10.0'
                  display_amount: "$10.00"
                  status: checkout
                  source_type: store_credit
                  source_id: credit_UkLWZg9DAJ
                  source:
                    id: credit_UkLWZg9DAJ
                    amount: '50.0'
                    amount_used: '0.0'
                    amount_remaining: '50.0'
                    display_amount: "$50.00"
                    display_amount_used: "$0.00"
                    display_amount_remaining: "$50.00"
                    currency: USD
                  payment_method:
                    id: pm_UkLWZg9DAJ
                    name: Store Credit
                    description: Store Credit
                    type: store_credit
                    session_required: false
                    source_required: true
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 324 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: 325 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:
                - id: pm_UkLWZg9DAJ
                  name: Store Credit
                  description: Store Credit
                  type: store_credit
                  session_required: false
                  source_required: true
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
        '422':
          description: no store credit available
          content:
            application/json:
              example:
                error:
                  code: processing_error
                  message: User does not have any Store Credits available
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  example: 10.0
                  description: Amount to apply (optional - defaults to max available)
    delete:
      summary: Remove store credit
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Removes store credit from the cart.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const cart = await client.carts.storeCredits.remove('cart_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: store credit removed
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R554787846
                token: vfB6PnFw9cPg6LbJqQKBA7jHh5zQGzRLtnz
                email: elvis@hyatt.ca
                customer_note:
                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_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 1673494
                  slug: product-1673494
                  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:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments:
                - id: ful_UkLWZg9DAJ
                  number: H45381203670
                  tracking: U10000
                  tracking_url:
                  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:
                  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: Ozella Hirthe
                    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: 332 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: 333 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:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
  "/api/v3/store/wishlists":
    get:
      summary: List wishlists
      tags:
      - Wishlists
      security:
      - api_key: []
        bearer_auth: []
      description: Returns all wishlists for the authenticated customer
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const wishlists = await client.wishlists.list({}, {
            token: '<token>',
          })
      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
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: wishlists found
          content:
            application/json:
              example:
                data:
                - id: wl_UkLWZg9DAJ
                  name: My Wishlist
                  token: czkimqa2wGQpziZPiHu4TETD
                  is_default: false
                  is_private: true
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Wishlist"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    post:
      summary: Create a wishlist
      tags:
      - Wishlists
      security:
      - api_key: []
        bearer_auth: []
      description: Creates a new wishlist for the customer
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const wishlist = await client.wishlists.create({
            name: 'Birthday Ideas',
            is_private: true,
          }, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '201':
          description: wishlist created
          content:
            application/json:
              example:
                id: wl_gbHJdmfrXB
                name: Birthday Ideas
                token: HkhGZqtmkmgvuTiENz7zMHwA
                is_default: false
                is_private: true
              schema:
                "$ref": "#/components/schemas/Wishlist"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Name can't be blank
                  details:
                    name:
                    - can't be blank
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Birthday Ideas
                is_private:
                  type: boolean
                  example: true
                is_default:
                  type: boolean
                  example: false
              required:
              - name
  "/api/v3/store/wishlists/{id}":
    get:
      summary: Get a wishlist
      tags:
      - Wishlists
      security:
      - api_key: []
        bearer_auth: []
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const wishlist = await client.wishlists.get('wl_abc123', {
            expand: ['wished_items'],
          }, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Expand wished_items
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: wishlist found
          content:
            application/json:
              example:
                id: wl_UkLWZg9DAJ
                name: My Wishlist
                token: URczbyJbeCgRS1a82JhitHvQ
                is_default: false
                is_private: true
              schema:
                "$ref": "#/components/schemas/Wishlist"
        '404':
          description: wishlist not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Wishlist not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update a wishlist
      tags:
      - Wishlists
      security:
      - api_key: []
        bearer_auth: []
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const wishlist = await client.wishlists.update('wl_abc123', {
            name: 'Updated Name',
          }, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: wishlist updated
          content:
            application/json:
              example:
                id: wl_UkLWZg9DAJ
                name: Updated Name
                token: RbsVopS8AJBteR6s51rRT9tN
                is_default: false
                is_private: true
              schema:
                "$ref": "#/components/schemas/Wishlist"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Updated Name
                is_private:
                  type: boolean
                  example: true
                is_default:
                  type: boolean
                  example: false
    delete:
      summary: Delete a wishlist
      tags:
      - Wishlists
      security:
      - api_key: []
        bearer_auth: []
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          await client.wishlists.delete('wl_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: wishlist deleted
  "/api/v3/store/wishlists/{wishlist_id}/items":
    post:
      summary: Add item to wishlist
      tags:
      - Wishlists
      security:
      - api_key: []
        bearer_auth: []
      description: Adds a variant to the wishlist
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          const item = await client.wishlists.items.create('wl_abc123', {
            variant_id: 'variant_abc123',
            quantity: 1,
          }, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: wishlist_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: item added
          content:
            application/json:
              example:
                id: wi_gbHJdmfrXB
                variant_id: variant_gbHJdmfrXB
                wishlist_id: wl_UkLWZg9DAJ
                quantity: 1
                variant:
                  id: variant_gbHJdmfrXB
                  product_id: prod_gbHJdmfrXB
                  sku: SKU-202
                  options_text: ''
                  track_inventory: true
                  media_count: 0
                  thumbnail_url:
                  purchasable: true
                  in_stock: false
                  backorderable: true
                  weight: 0.0
                  height:
                  width:
                  depth:
                  price:
                    id: price_gbHJdmfrXB
                    amount: '19.99'
                    amount_in_cents: 1999
                    compare_at_amount:
                    compare_at_amount_in_cents:
                    currency: USD
                    display_amount: "$19.99"
                    display_compare_at_amount:
                    price_list_id:
                  original_price:
                  option_values: []
              schema:
                "$ref": "#/components/schemas/WishlistItem"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                variant_id:
                  type: string
                  example: variant_abc123
                quantity:
                  type: integer
                  example: 1
              required:
              - variant_id
  "/api/v3/store/wishlists/{wishlist_id}/items/{id}":
    delete:
      summary: Remove item from wishlist
      tags:
      - Wishlists
      security:
      - api_key: []
        bearer_auth: []
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

          const client = createClient({
            baseUrl: 'https://your-store.com',
            publishableKey: '<api-key>',
          })

          await client.wishlists.items.delete('wl_abc123', 'wi_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: wishlist_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: item removed
        '404':
          description: item not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Wished item not found
servers:
- url: http://{defaultHost}
  variables:
    defaultHost:
      default: localhost:3000
tags:
- name: Authentication
  description: Customer authentication (login, logout, token refresh)
- name: Product Catalog
  description: Products and categories
- name: Carts
  description: Shopping cart management
- name: Orders
  description: Order lookup
- name: Customers
  description: Customer account, addresses, saved payment methods, and order history
- name: Markets
  description: Markets, countries, currencies, and locales
- name: Wishlists
  description: Customer wishlists
- name: Newsletter Subscribers
  description: Guest and customer newsletter subscriptions (double opt-in)
- name: Policies
  description: Store policies (return policy, privacy policy, terms of service)
- name: Digitals
  description: Digital product downloads
x-tagGroups:
- name: Authentication
  tags:
  - Authentication
- name: Product Catalog
  tags:
  - Product Catalog
- name: Carts
  tags:
  - Carts
- name: Orders
  tags:
  - Orders
- name: Customers
  tags:
  - Customers
- name: Markets
  tags:
  - Markets
- name: Wishlists
  tags:
  - Wishlists
- name: Newsletter Subscribers
  tags:
  - Newsletter Subscribers
- name: Policies
  tags:
  - Policies
- name: Digitals
  tags:
  - Digitals
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-spree-api-key
      in: header
      description: Publishable API key for store access
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for authenticated customers
  schemas:
    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 25
        count:
          type: integer
          example: 100
          description: Total number of records
        pages:
          type: integer
          example: 4
          description: Total number of pages
        from:
          type: integer
          example: 1
          description: Index of first record on this page
        to:
          type: integer
          example: 25
          description: Index of last record on this page
        in:
          type: integer
          example: 25
          description: Number of records on this page
        previous:
          type: integer
          nullable: true
          example:
          description: Previous page number
        next:
          type: integer
          nullable: true
          example: 2
          description: Next page number
      required:
      - page
      - limit
      - count
      - pages
      - from
      - to
      - in
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: record_not_found
            message:
              type: string
              example: Record not found
            details:
              type: object
              description: Field-specific validation errors
              nullable: true
              example:
                name:
                - is too short
                - is required
                email:
                - is invalid
          required:
          - code
          - message
      required:
      - error
      example:
        error:
          code: validation_error
          message: Validation failed
          details:
            name:
            - is too short
            email:
            - is invalid
    AuthResponse:
      type: object
      properties:
        token:
          type: string
          description: JWT access token
        refresh_token:
          type: string
          description: Refresh token for obtaining new access tokens
        user:
          "$ref": "#/components/schemas/Customer"
      required:
      - token
      - refresh_token
      - user
    PermissionRule:
      type: object
      description: A single permission rule (CanCanCan rule). Rules are applied in
        order, last-matching-wins.
      properties:
        allow:
          type: boolean
          description: true for `can`, false for `cannot`
        actions:
          type: array
          items:
            type: string
          description: Action names, e.g. ["read", "update"] or ["manage"]
        subjects:
          type: array
          items:
            type: string
          description: Subject class names, e.g. ["Spree::Product"] or ["all"]
        has_conditions:
          type: boolean
          description: True if the server-side rule has per-record conditions. The
            SPA shows the action optimistically and handles 403 from the API.
      required:
      - allow
      - actions
      - subjects
      - has_conditions
    MeResponse:
      type: object
      description: Current admin user profile and serialized permissions
      properties:
        user:
          "$ref": "#/components/schemas/AdminUser"
        permissions:
          type: array
          items:
            "$ref": "#/components/schemas/PermissionRule"
      required:
      - user
      - permissions
    CheckoutRequirement:
      type: object
      properties:
        step:
          type: string
          description: Checkout step this requirement belongs to
          example: payment
        field:
          type: string
          description: Field that needs to be satisfied
          example: payment
        message:
          type: string
          description: Human-readable requirement message
          example: Add a payment method
      required:
      - step
      - field
      - message
    CartWarning:
      type: object
      description: A warning about a cart issue (e.g., item removed due to stock change)
      properties:
        code:
          type: string
          description: Machine-readable warning code
          example: line_item_removed
        message:
          type: string
          description: Human-readable warning message
          example: Blue T-Shirt was removed because it was sold out
        line_item_id:
          type: string
          nullable: true
          description: Prefixed line item ID (when applicable)
          example: li_abc123
        variant_id:
          type: string
          nullable: true
          description: Prefixed variant ID (when applicable)
          example: variant_abc123
      required:
      - code
      - message
    FulfillmentManifestItem:
      type: object
      description: An item within a fulfillment — which line item and how many units
        are in this fulfillment
      properties:
        item_id:
          type: string
          description: Line item ID
          example: li_abc123
        variant_id:
          type: string
          description: Variant ID
          example: variant_abc123
        quantity:
          type: integer
          description: Quantity in this fulfillment
          example: 2
      required:
      - item_id
      - variant_id
      - quantity
    AdminUserRoleAssignment:
      type: object
      description: A role assignment for the current store on a staff member
      properties:
        id:
          type: string
          description: Prefixed role ID
          example: role_abc123
        name:
          type: string
          description: Role name
          example: admin
      required:
      - id
      - name
    PreferenceField:
      type: object
      description: A single configurable preference on a payment method, promotion
        rule/action, or calculator. The frontend uses `type` + `default` to render
        a sensible input.
      properties:
        key:
          type: string
          example: amount_min
        type:
          type: string
          example: decimal
          description: string | text | password | integer | decimal | boolean | array
            | hash
        default:
          description: Default value (any JSON type), null when there is no default
          nullable: true
      required:
      - key
      - type
    PromotionActionCalculator:
      type: object
      description: The action's nested calculator (when the action carries one — null
        for actions like `free_shipping`)
      properties:
        type:
          type: string
          example: flat_rate
          description: Wire shorthand for the calculator subclass
        label:
          type: string
          example: Flat Rate
        preferences:
          type: object
          additionalProperties: true
        preference_schema:
          type: array
          items:
            "$ref": "#/components/schemas/PreferenceField"
      required:
      - type
      - label
      - preferences
      - preference_schema
    PromotionActionLineItem:
      type: object
      description: One row in a `create_line_items` action — the variant added to
        the order and how many
      properties:
        variant_id:
          type: string
          example: variant_abc123
        quantity:
          type: integer
          example: 1
      required:
      - variant_id
      - quantity
    Address:
      type: object
      properties:
        id:
          type: string
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        full_name:
          type: string
        address1:
          type: string
          nullable: true
        address2:
          type: string
          nullable: true
        postal_code:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        company:
          type: string
          nullable: true
        country_name:
          type: string
        country_iso:
          type: string
        state_text:
          type: string
          nullable: true
        state_abbr:
          type: string
          nullable: true
        quick_checkout:
          type: boolean
        is_default_billing:
          type: boolean
        is_default_shipping:
          type: boolean
        state_name:
          type: string
          nullable: true
      required:
      - id
      - first_name
      - last_name
      - full_name
      - address1
      - address2
      - postal_code
      - city
      - phone
      - company
      - country_name
      - country_iso
      - state_text
      - state_abbr
      - quick_checkout
      - is_default_billing
      - is_default_shipping
      - state_name
      x-typelizer: true
    Base:
      type: object
      properties:
        id:
          type: string
      required:
      - id
      x-typelizer: true
    Cart:
      type: object
      properties:
        id:
          type: string
        market_id:
          type: string
          nullable: true
        number:
          type: string
        token:
          type: string
        email:
          type: string
          nullable: true
        customer_note:
          type: string
          nullable: true
        currency:
          type: string
        locale:
          type: string
          nullable: true
        total_quantity:
          type: number
        item_total:
          type: string
        display_item_total:
          type: string
        adjustment_total:
          type: string
        display_adjustment_total:
          type: string
        discount_total:
          type: string
        display_discount_total:
          type: string
        tax_total:
          type: string
        display_tax_total:
          type: string
        included_tax_total:
          type: string
        display_included_tax_total:
          type: string
        additional_tax_total:
          type: string
        display_additional_tax_total:
          type: string
        total:
          type: string
        display_total:
          type: string
        gift_card_total:
          type: string
        display_gift_card_total:
          type: string
        amount_due:
          type: string
        display_amount_due:
          type: string
        delivery_total:
          type: string
        display_delivery_total:
          type: string
        warnings:
          type: array
          items:
            "$ref": "#/components/schemas/CartWarning"
        store_credit_total:
          type: string
        display_store_credit_total:
          type: string
        covered_by_store_credit:
          type: boolean
        current_step:
          type: string
        completed_steps:
          type: array
          items:
            type: string
        requirements:
          type: array
          items:
            "$ref": "#/components/schemas/CheckoutRequirement"
        shipping_eq_billing_address:
          type: boolean
        discounts:
          type: array
          items:
            "$ref": "#/components/schemas/Discount"
        items:
          type: array
          items:
            "$ref": "#/components/schemas/LineItem"
        fulfillments:
          type: array
          items:
            "$ref": "#/components/schemas/Fulfillment"
        payments:
          type: array
          items:
            "$ref": "#/components/schemas/Payment"
        billing_address:
          allOf:
          - "$ref": "#/components/schemas/Address"
          nullable: true
        shipping_address:
          allOf:
          - "$ref": "#/components/schemas/Address"
          nullable: true
        payment_methods:
          type: array
          items:
            "$ref": "#/components/schemas/PaymentMethod"
        gift_card:
          allOf:
          - "$ref": "#/components/schemas/GiftCard"
          nullable: true
        market:
          allOf:
          - "$ref": "#/components/schemas/Market"
          nullable: true
      required:
      - id
      - market_id
      - number
      - token
      - email
      - customer_note
      - currency
      - locale
      - total_quantity
      - item_total
      - display_item_total
      - adjustment_total
      - display_adjustment_total
      - discount_total
      - display_discount_total
      - tax_total
      - display_tax_total
      - included_tax_total
      - display_included_tax_total
      - additional_tax_total
      - display_additional_tax_total
      - total
      - display_total
      - gift_card_total
      - display_gift_card_total
      - amount_due
      - display_amount_due
      - delivery_total
      - display_delivery_total
      - warnings
      - store_credit_total
      - display_store_credit_total
      - covered_by_store_credit
      - current_step
      - completed_steps
      - requirements
      - shipping_eq_billing_address
      - discounts
      - items
      - fulfillments
      - payments
      - billing_address
      - shipping_address
      - payment_methods
      - gift_card
      - market
      x-typelizer: true
    Category:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        permalink:
          type: string
        position:
          type: number
        depth:
          type: number
        meta_title:
          type: string
          nullable: true
        meta_description:
          type: string
          nullable: true
        meta_keywords:
          type: string
          nullable: true
        children_count:
          type: number
        parent_id:
          type: string
          nullable: true
        description:
          type: string
        description_html:
          type: string
        image_url:
          type: string
          nullable: true
        square_image_url:
          type: string
          nullable: true
        is_root:
          type: boolean
        is_child:
          type: boolean
        is_leaf:
          type: boolean
        parent:
          "$ref": "#/components/schemas/Category"
        children:
          type: array
          items:
            "$ref": "#/components/schemas/Category"
        ancestors:
          type: array
          items:
            "$ref": "#/components/schemas/Category"
        custom_fields:
          type: array
          items:
            "$ref": "#/components/schemas/CustomField"
      required:
      - id
      - name
      - permalink
      - position
      - depth
      - meta_title
      - meta_description
      - meta_keywords
      - children_count
      - parent_id
      - description
      - description_html
      - image_url
      - square_image_url
      - is_root
      - is_child
      - is_leaf
      x-typelizer: true
    Channel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        code:
          type: string
        active:
          type: boolean
      required:
      - id
      - name
      - code
      - active
      x-typelizer: true
    Country:
      type: object
      properties:
        iso:
          type: string
        iso3:
          type: string
        name:
          type: string
        states_required:
          type: boolean
        zipcode_required:
          type: boolean
        states:
          type: array
          items:
            "$ref": "#/components/schemas/State"
        market:
          allOf:
          - "$ref": "#/components/schemas/Market"
          nullable: true
      required:
      - iso
      - iso3
      - name
      - states_required
      - zipcode_required
      x-typelizer: true
    CreditCard:
      type: object
      properties:
        id:
          type: string
        brand:
          type: string
        last4:
          type: string
        month:
          type: number
        year:
          type: number
        name:
          type: string
          nullable: true
        default:
          type: boolean
        gateway_payment_profile_id:
          type: string
          nullable: true
      required:
      - id
      - brand
      - last4
      - month
      - year
      - name
      - default
      - gateway_payment_profile_id
      x-typelizer: true
    Currency:
      type: object
      properties:
        iso_code:
          type: string
        name:
          type: string
        symbol:
          type: string
      required:
      - iso_code
      - name
      - symbol
      x-typelizer: true
    CustomField:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        type:
          type: string
          deprecated: true
        field_type:
          type: string
          enum:
          - short_text
          - long_text
          - rich_text
          - number
          - boolean
          - json
        key:
          type: string
        value:
          type: object
      required:
      - id
      - label
      - type
      - field_type
      - key
      - value
      x-typelizer: true
    Customer:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        accepts_email_marketing:
          type: boolean
        full_name:
          type: string
        available_store_credit_total:
          type: string
        display_available_store_credit_total:
          type: string
        addresses:
          type: array
          items:
            "$ref": "#/components/schemas/Address"
        default_billing_address:
          allOf:
          - "$ref": "#/components/schemas/Address"
          nullable: true
        default_shipping_address:
          allOf:
          - "$ref": "#/components/schemas/Address"
          nullable: true
      required:
      - id
      - email
      - first_name
      - last_name
      - phone
      - accepts_email_marketing
      - full_name
      - available_store_credit_total
      - display_available_store_credit_total
      - addresses
      - default_billing_address
      - default_shipping_address
      x-typelizer: true
    DeliveryMethod:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        code:
          type: string
          nullable: true
      required:
      - id
      - name
      - code
      x-typelizer: true
    DeliveryRate:
      type: object
      properties:
        id:
          type: string
        delivery_method_id:
          type: string
        name:
          type: string
        selected:
          type: boolean
        cost:
          type: string
        total:
          type: string
        additional_tax_total:
          type: string
        included_tax_total:
          type: string
        tax_total:
          type: string
        display_cost:
          type: string
        display_total:
          type: string
        display_additional_tax_total:
          type: string
        display_included_tax_total:
          type: string
        display_tax_total:
          type: string
        delivery_method:
          "$ref": "#/components/schemas/DeliveryMethod"
      required:
      - id
      - delivery_method_id
      - name
      - selected
      - cost
      - total
      - additional_tax_total
      - included_tax_total
      - tax_total
      - display_cost
      - display_total
      - display_additional_tax_total
      - display_included_tax_total
      - display_tax_total
      - delivery_method
      x-typelizer: true
    DigitalLink:
      type: object
      properties:
        id:
          type: string
        access_counter:
          type: number
        filename:
          type: string
        content_type:
          type: string
        download_url:
          type: string
        authorizable:
          type: boolean
        expired:
          type: boolean
        access_limit_exceeded:
          type: boolean
      required:
      - id
      - access_counter
      - filename
      - content_type
      - download_url
      - authorizable
      - expired
      - access_limit_exceeded
      x-typelizer: true
    Digital:
      type: object
      properties:
        id:
          type: string
        created_at:
          type: string
        updated_at:
          type: string
        variant_id:
          type: string
          nullable: true
      required:
      - id
      - created_at
      - updated_at
      - variant_id
      x-typelizer: true
    Discount:
      type: object
      properties:
        id:
          type: string
        promotion_id:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        code:
          type: string
          nullable: true
        amount:
          type: string
        display_amount:
          type: string
      required:
      - id
      - promotion_id
      - name
      - description
      - code
      - amount
      - display_amount
      x-typelizer: true
    Fulfillment:
      type: object
      properties:
        id:
          type: string
        number:
          type: string
        tracking:
          type: string
          nullable: true
        tracking_url:
          type: string
          nullable: true
        cost:
          type: string
        display_cost:
          type: string
        total:
          type: string
        display_total:
          type: string
        discount_total:
          type: string
        display_discount_total:
          type: string
        additional_tax_total:
          type: string
        display_additional_tax_total:
          type: string
        included_tax_total:
          type: string
        display_included_tax_total:
          type: string
        tax_total:
          type: string
        display_tax_total:
          type: string
        status:
          type: string
        fulfillment_type:
          type: string
        fulfilled_at:
          type: string
          nullable: true
        items:
          type: array
          items:
            "$ref": "#/components/schemas/FulfillmentManifestItem"
        delivery_method:
          "$ref": "#/components/schemas/DeliveryMethod"
        stock_location:
          "$ref": "#/components/schemas/StockLocation"
        delivery_rates:
          type: array
          items:
            "$ref": "#/components/schemas/DeliveryRate"
      required:
      - id
      - number
      - tracking
      - tracking_url
      - cost
      - display_cost
      - total
      - display_total
      - discount_total
      - display_discount_total
      - additional_tax_total
      - display_additional_tax_total
      - included_tax_total
      - display_included_tax_total
      - tax_total
      - display_tax_total
      - status
      - fulfillment_type
      - fulfilled_at
      - items
      - delivery_method
      - stock_location
      - delivery_rates
      x-typelizer: true
    GiftCardBatch:
      type: object
      properties:
        id:
          type: string
        codes_count:
          type: number
        currency:
          type: string
          nullable: true
        prefix:
          type: string
          nullable: true
        created_at:
          type: string
        updated_at:
          type: string
        amount:
          type: string
          nullable: true
        expires_at:
          type: string
          nullable: true
        created_by_id:
          type: string
          nullable: true
      required:
      - id
      - codes_count
      - currency
      - prefix
      - created_at
      - updated_at
      - amount
      - expires_at
      - created_by_id
      x-typelizer: true
    GiftCard:
      type: object
      properties:
        id:
          type: string
        code:
          type: string
        status:
          type: string
        currency:
          type: string
        amount:
          type: string
        amount_used:
          type: string
        amount_authorized:
          type: string
        amount_remaining:
          type: string
        display_amount:
          type: string
        display_amount_used:
          type: string
        display_amount_remaining:
          type: string
        expires_at:
          type: string
          nullable: true
        redeemed_at:
          type: string
          nullable: true
        expired:
          type: boolean
        active:
          type: boolean
      required:
      - id
      - code
      - status
      - currency
      - amount
      - amount_used
      - amount_authorized
      - amount_remaining
      - display_amount
      - display_amount_used
      - display_amount_remaining
      - expires_at
      - redeemed_at
      - expired
      - active
      x-typelizer: true
    Invitation:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        resource_type:
          type: string
          nullable: true
        inviter_type:
          type: string
          nullable: true
        invitee_type:
          type: string
          nullable: true
        created_at:
          type: string
        updated_at:
          type: string
        status:
          type: string
        resource_id:
          type: string
          nullable: true
        inviter_id:
          type: string
          nullable: true
        invitee_id:
          type: string
          nullable: true
        role_id:
          type: string
          nullable: true
        expires_at:
          type: string
          nullable: true
        accepted_at:
          type: string
          nullable: true
      required:
      - id
      - email
      - resource_type
      - inviter_type
      - invitee_type
      - created_at
      - updated_at
      - status
      - resource_id
      - inviter_id
      - invitee_id
      - role_id
      - expires_at
      - accepted_at
      x-typelizer: true
    LineItem:
      type: object
      properties:
        id:
          type: string
        variant_id:
          type: string
        quantity:
          type: number
        currency:
          type: string
        name:
          type: string
        slug:
          type: string
        options_text:
          type: string
        price:
          type: string
        display_price:
          type: string
        total:
          type: string
        display_total:
          type: string
        adjustment_total:
          type: string
        display_adjustment_total:
          type: string
        additional_tax_total:
          type: string
        display_additional_tax_total:
          type: string
        included_tax_total:
          type: string
        display_included_tax_total:
          type: string
        discount_total:
          type: string
        display_discount_total:
          type: string
        pre_tax_amount:
          type: string
        display_pre_tax_amount:
          type: string
        discounted_amount:
          type: string
        display_discounted_amount:
          type: string
        display_compare_at_amount:
          type: string
          nullable: true
        compare_at_amount:
          type: string
          nullable: true
        thumbnail_url:
          type: string
          nullable: true
        option_values:
          type: array
          items:
            "$ref": "#/components/schemas/OptionValue"
        digital_links:
          type: array
          items:
            "$ref": "#/components/schemas/DigitalLink"
      required:
      - id
      - variant_id
      - quantity
      - currency
      - name
      - slug
      - options_text
      - price
      - display_price
      - total
      - display_total
      - adjustment_total
      - display_adjustment_total
      - additional_tax_total
      - display_additional_tax_total
      - included_tax_total
      - display_included_tax_total
      - discount_total
      - display_discount_total
      - pre_tax_amount
      - display_pre_tax_amount
      - discounted_amount
      - display_discounted_amount
      - display_compare_at_amount
      - compare_at_amount
      - thumbnail_url
      - option_values
      - digital_links
      x-typelizer: true
    Locale:
      type: object
      properties:
        code:
          type: string
        name:
          type: string
      required:
      - code
      - name
      x-typelizer: true
    Market:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        currency:
          type: string
        default_locale:
          type: string
        tax_inclusive:
          type: boolean
        default:
          type: boolean
        supported_locales:
          type: array
          items:
            type: string
        countries:
          type: array
          items:
            "$ref": "#/components/schemas/Country"
      required:
      - id
      - name
      - currency
      - default_locale
      - tax_inclusive
      - default
      - supported_locales
      x-typelizer: true
    Media:
      type: object
      properties:
        id:
          type: string
        product_id:
          type: string
          nullable: true
        variant_ids:
          type: array
          items:
            type: string
        position:
          type: number
        alt:
          type: string
          nullable: true
        media_type:
          type: string
        focal_point_x:
          type: number
          nullable: true
        focal_point_y:
          type: number
          nullable: true
        external_video_url:
          type: string
          nullable: true
        original_url:
          type: string
          nullable: true
        mini_url:
          type: string
          nullable: true
        small_url:
          type: string
          nullable: true
        medium_url:
          type: string
          nullable: true
        large_url:
          type: string
          nullable: true
        xlarge_url:
          type: string
          nullable: true
        og_image_url:
          type: string
          nullable: true
      required:
      - id
      - product_id
      - variant_ids
      - position
      - alt
      - media_type
      - focal_point_x
      - focal_point_y
      - external_video_url
      - original_url
      - mini_url
      - small_url
      - medium_url
      - large_url
      - xlarge_url
      - og_image_url
      x-typelizer: true
    NewsletterSubscriber:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        created_at:
          type: string
        updated_at:
          type: string
        verified:
          type: boolean
        verified_at:
          type: string
          nullable: true
        customer_id:
          type: string
          nullable: true
      required:
      - id
      - email
      - created_at
      - updated_at
      - verified
      - verified_at
      - customer_id
      x-typelizer: true
    OptionType:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        label:
          type: string
        position:
          type: number
        kind:
          type: string
      required:
      - id
      - name
      - label
      - position
      - kind
      x-typelizer: true
    OptionValue:
      type: object
      properties:
        id:
          type: string
        option_type_id:
          type: string
        name:
          type: string
        label:
          type: string
        position:
          type: number
        color_code:
          type: string
          nullable: true
        option_type_name:
          type: string
        option_type_label:
          type: string
        image_url:
          type: string
          nullable: true
      required:
      - id
      - option_type_id
      - name
      - label
      - position
      - color_code
      - option_type_name
      - option_type_label
      - image_url
      x-typelizer: true
    Order:
      type: object
      properties:
        id:
          type: string
        market_id:
          type: string
          nullable: true
        channel_id:
          type: string
          nullable: true
        number:
          type: string
        email:
          type: string
        customer_note:
          type: string
          nullable: true
        currency:
          type: string
        locale:
          type: string
          nullable: true
        total_quantity:
          type: number
        item_total:
          type: string
        display_item_total:
          type: string
        adjustment_total:
          type: string
        display_adjustment_total:
          type: string
        discount_total:
          type: string
        display_discount_total:
          type: string
        tax_total:
          type: string
        display_tax_total:
          type: string
        included_tax_total:
          type: string
        display_included_tax_total:
          type: string
        additional_tax_total:
          type: string
        display_additional_tax_total:
          type: string
        total:
          type: string
        display_total:
          type: string
        gift_card_total:
          type: string
        display_gift_card_total:
          type: string
        amount_due:
          type: string
        display_amount_due:
          type: string
        delivery_total:
          type: string
        display_delivery_total:
          type: string
        fulfillment_status:
          type: string
          nullable: true
        payment_status:
          type: string
          nullable: true
        completed_at:
          type: string
          nullable: true
        store_credit_total:
          type: string
        display_store_credit_total:
          type: string
        covered_by_store_credit:
          type: boolean
        discounts:
          type: array
          items:
            "$ref": "#/components/schemas/Discount"
        items:
          type: array
          items:
            "$ref": "#/components/schemas/LineItem"
        fulfillments:
          type: array
          items:
            "$ref": "#/components/schemas/Fulfillment"
        payments:
          type: array
          items:
            "$ref": "#/components/schemas/Payment"
        billing_address:
          allOf:
          - "$ref": "#/components/schemas/Address"
          nullable: true
        shipping_address:
          allOf:
          - "$ref": "#/components/schemas/Address"
          nullable: true
        gift_card:
          allOf:
          - "$ref": "#/components/schemas/GiftCard"
          nullable: true
        market:
          allOf:
          - "$ref": "#/components/schemas/Market"
          nullable: true
      required:
      - id
      - market_id
      - channel_id
      - number
      - email
      - customer_note
      - currency
      - locale
      - total_quantity
      - item_total
      - display_item_total
      - adjustment_total
      - display_adjustment_total
      - discount_total
      - display_discount_total
      - tax_total
      - display_tax_total
      - included_tax_total
      - display_included_tax_total
      - additional_tax_total
      - display_additional_tax_total
      - total
      - display_total
      - gift_card_total
      - display_gift_card_total
      - amount_due
      - display_amount_due
      - delivery_total
      - display_delivery_total
      - fulfillment_status
      - payment_status
      - completed_at
      - store_credit_total
      - display_store_credit_total
      - covered_by_store_credit
      - discounts
      - items
      - fulfillments
      - payments
      - billing_address
      - shipping_address
      - gift_card
      - market
      x-typelizer: true
    PaymentMethod:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        type:
          type: string
        session_required:
          type: boolean
        source_required:
          type: boolean
      required:
      - id
      - name
      - description
      - type
      - session_required
      - source_required
      x-typelizer: true
    Payment:
      type: object
      properties:
        id:
          type: string
        payment_method_id:
          type: string
        response_code:
          type: string
          nullable: true
        number:
          type: string
        amount:
          type: string
        display_amount:
          type: string
        status:
          type: string
        source_type:
          type: string
          nullable: true
          enum:
          - credit_card
          - store_credit
          - payment_source
        source_id:
          type: string
          nullable: true
        source:
          anyOf:
          - "$ref": "#/components/schemas/CreditCard"
          - "$ref": "#/components/schemas/StoreCredit"
          - "$ref": "#/components/schemas/PaymentSource"
          nullable: true
        payment_method:
          "$ref": "#/components/schemas/PaymentMethod"
      required:
      - id
      - payment_method_id
      - response_code
      - number
      - amount
      - display_amount
      - status
      - source_type
      - source_id
      - source
      - payment_method
      x-typelizer: true
    PaymentSession:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        currency:
          type: string
        external_id:
          type: string
        external_data:
          type: object
        customer_external_id:
          type: string
          nullable: true
        expires_at:
          type: string
          nullable: true
        amount:
          type: string
        payment_method_id:
          type: string
        order_id:
          type: string
        payment_method:
          "$ref": "#/components/schemas/PaymentMethod"
        payment:
          "$ref": "#/components/schemas/Payment"
      required:
      - id
      - status
      - currency
      - external_id
      - external_data
      - customer_external_id
      - expires_at
      - amount
      - payment_method_id
      - order_id
      - payment_method
      x-typelizer: true
    PaymentSetupSession:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        external_id:
          type: string
          nullable: true
        external_client_secret:
          type: string
          nullable: true
        external_data:
          type: object
        payment_method_id:
          type: string
          nullable: true
        payment_source_id:
          type: string
          nullable: true
        payment_source_type:
          type: string
          nullable: true
        customer_id:
          type: string
          nullable: true
        payment_method:
          "$ref": "#/components/schemas/PaymentMethod"
      required:
      - id
      - status
      - external_id
      - external_client_secret
      - external_data
      - payment_method_id
      - payment_source_id
      - payment_source_type
      - customer_id
      - payment_method
      x-typelizer: true
    PaymentSource:
      type: object
      properties:
        id:
          type: string
        gateway_payment_profile_id:
          type: string
          nullable: true
      required:
      - id
      - gateway_payment_profile_id
      x-typelizer: true
    Policy:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        body:
          type: string
          nullable: true
        body_html:
          type: string
          nullable: true
      required:
      - id
      - name
      - slug
      - body
      - body_html
      x-typelizer: true
    PriceHistory:
      type: object
      properties:
        id:
          type: string
        amount:
          type: string
        amount_in_cents:
          type: number
        currency:
          type: string
        display_amount:
          type: string
        recorded_at:
          type: string
      required:
      - id
      - amount
      - amount_in_cents
      - currency
      - display_amount
      - recorded_at
      x-typelizer: true
    Price:
      type: object
      properties:
        id:
          type: string
        amount:
          type: string
          nullable: true
        amount_in_cents:
          type: number
          nullable: true
        compare_at_amount:
          type: string
          nullable: true
        compare_at_amount_in_cents:
          type: number
          nullable: true
        currency:
          type: string
          nullable: true
        display_amount:
          type: string
          nullable: true
        display_compare_at_amount:
          type: string
          nullable: true
        price_list_id:
          type: string
          nullable: true
      required:
      - id
      - amount
      - amount_in_cents
      - compare_at_amount
      - compare_at_amount_in_cents
      - currency
      - display_amount
      - display_compare_at_amount
      - price_list_id
      x-typelizer: true
    Product:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        meta_title:
          type: string
          nullable: true
        meta_description:
          type: string
          nullable: true
        meta_keywords:
          type: string
          nullable: true
        variant_count:
          type: number
        available_on:
          type: string
          nullable: true
        purchasable:
          type: boolean
        in_stock:
          type: boolean
        backorderable:
          type: boolean
        available:
          type: boolean
        description:
          type: string
          nullable: true
        description_html:
          type: string
          nullable: true
        default_variant_id:
          type: string
        thumbnail_url:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: string
        price:
          "$ref": "#/components/schemas/Price"
        original_price:
          allOf:
          - "$ref": "#/components/schemas/Price"
          nullable: true
        primary_media:
          "$ref": "#/components/schemas/Media"
        media:
          type: array
          items:
            "$ref": "#/components/schemas/Media"
        variants:
          type: array
          items:
            "$ref": "#/components/schemas/Variant"
        default_variant:
          "$ref": "#/components/schemas/Variant"
        option_types:
          type: array
          items:
            "$ref": "#/components/schemas/OptionType"
        categories:
          type: array
          items:
            "$ref": "#/components/schemas/Category"
        custom_fields:
          type: array
          items:
            "$ref": "#/components/schemas/CustomField"
        prior_price:
          allOf:
          - "$ref": "#/components/schemas/PriceHistory"
          nullable: true
      required:
      - id
      - name
      - slug
      - meta_title
      - meta_description
      - meta_keywords
      - variant_count
      - available_on
      - purchasable
      - in_stock
      - backorderable
      - available
      - description
      - description_html
      - default_variant_id
      - thumbnail_url
      - tags
      - price
      - original_price
      x-typelizer: true
    Promotion:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        code:
          type: string
          nullable: true
      required:
      - id
      - name
      - description
      - code
      x-typelizer: true
    Refund:
      type: object
      properties:
        id:
          type: string
        transaction_id:
          type: string
          nullable: true
        amount:
          type: string
          nullable: true
        payment_id:
          type: string
          nullable: true
        refund_reason_id:
          type: string
          nullable: true
        reimbursement_id:
          type: string
          nullable: true
      required:
      - id
      - transaction_id
      - amount
      - payment_id
      - refund_reason_id
      - reimbursement_id
      x-typelizer: true
    ReturnAuthorization:
      type: object
      properties:
        id:
          type: string
        number:
          type: string
        status:
          type: string
        order_id:
          type: string
          nullable: true
        stock_location_id:
          type: string
          nullable: true
        return_authorization_reason_id:
          type: string
          nullable: true
      required:
      - id
      - number
      - status
      - order_id
      - stock_location_id
      - return_authorization_reason_id
      x-typelizer: true
    ReturnItem:
      type: object
      properties:
        id:
          type: string
        reception_status:
          type: string
          nullable: true
        acceptance_status:
          type: string
          nullable: true
        created_at:
          type: string
        updated_at:
          type: string
        pre_tax_amount:
          type: string
          nullable: true
        included_tax_total:
          type: string
          nullable: true
        additional_tax_total:
          type: string
          nullable: true
        inventory_unit_id:
          type: string
          nullable: true
        return_authorization_id:
          type: string
          nullable: true
        customer_return_id:
          type: string
          nullable: true
        reimbursement_id:
          type: string
          nullable: true
        exchange_variant_id:
          type: string
          nullable: true
      required:
      - id
      - reception_status
      - acceptance_status
      - created_at
      - updated_at
      - pre_tax_amount
      - included_tax_total
      - additional_tax_total
      - inventory_unit_id
      - return_authorization_id
      - customer_return_id
      - reimbursement_id
      - exchange_variant_id
      x-typelizer: true
    State:
      type: object
      properties:
        abbr:
          type: string
        name:
          type: string
      required:
      - abbr
      - name
      x-typelizer: true
    StockLocation:
      type: object
      properties:
        id:
          type: string
        state_abbr:
          type: string
          nullable: true
        name:
          type: string
        address1:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        zipcode:
          type: string
          nullable: true
        country_iso:
          type: string
          nullable: true
        country_name:
          type: string
          nullable: true
        state_text:
          type: string
          nullable: true
      required:
      - id
      - state_abbr
      - name
      - address1
      - city
      - zipcode
      - country_iso
      - country_name
      - state_text
      x-typelizer: true
    StockReservation:
      type: object
      properties:
        id:
          type: string
      required:
      - id
      x-typelizer: true
    StoreCredit:
      type: object
      properties:
        id:
          type: string
        amount:
          type: string
        amount_used:
          type: string
        amount_remaining:
          type: string
        display_amount:
          type: string
        display_amount_used:
          type: string
        display_amount_remaining:
          type: string
        currency:
          type: string
      required:
      - id
      - amount
      - amount_used
      - amount_remaining
      - display_amount
      - display_amount_used
      - display_amount_remaining
      - currency
      x-typelizer: true
    Variant:
      type: object
      properties:
        id:
          type: string
        product_id:
          type: string
        sku:
          type: string
          nullable: true
        options_text:
          type: string
        track_inventory:
          type: boolean
        media_count:
          type: number
        thumbnail_url:
          type: string
          nullable: true
        purchasable:
          type: boolean
        in_stock:
          type: boolean
        backorderable:
          type: boolean
        weight:
          type: number
          nullable: true
        height:
          type: number
          nullable: true
        width:
          type: number
          nullable: true
        depth:
          type: number
          nullable: true
        price:
          "$ref": "#/components/schemas/Price"
        original_price:
          allOf:
          - "$ref": "#/components/schemas/Price"
          nullable: true
        primary_media:
          "$ref": "#/components/schemas/Media"
        media:
          type: array
          items:
            "$ref": "#/components/schemas/Media"
        option_values:
          type: array
          items:
            "$ref": "#/components/schemas/OptionValue"
        custom_fields:
          type: array
          items:
            "$ref": "#/components/schemas/CustomField"
        prior_price:
          allOf:
          - "$ref": "#/components/schemas/PriceHistory"
          nullable: true
      required:
      - id
      - product_id
      - sku
      - options_text
      - track_inventory
      - media_count
      - thumbnail_url
      - purchasable
      - in_stock
      - backorderable
      - weight
      - height
      - width
      - depth
      - price
      - original_price
      - option_values
      x-typelizer: true
    WishlistItem:
      type: object
      properties:
        id:
          type: string
        variant_id:
          type: string
        wishlist_id:
          type: string
        quantity:
          type: number
        variant:
          "$ref": "#/components/schemas/Variant"
      required:
      - id
      - variant_id
      - wishlist_id
      - quantity
      - variant
      x-typelizer: true
    Wishlist:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        token:
          type: string
        is_default:
          type: boolean
        is_private:
          type: boolean
        items:
          type: array
          items:
            "$ref": "#/components/schemas/WishlistItem"
      required:
      - id
      - name
      - token
      - is_default
      - is_private
      x-typelizer: true