---
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/auth/login":
    post:
      summary: Login
      tags:
      - Authentication
      security:
      - api_key: []
      description: |
        Authenticates a customer and returns a JWT access token + refresh token.

        The `provider` field selects the authentication method. When omitted it
        defaults to `email`, the built-in email/password login.

        To authenticate against a third-party identity provider (Auth0, Okta,
        Firebase, a custom JWT issuer, SAML, etc.), send
        `{ "provider": "<your_key>", ... }` with the fields that provider
        requires. The endpoint returns the same JWT + refresh token regardless of
        which provider authenticated the request. See
        [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)
        for the list of configured providers and their required fields.
      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.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6Ijk5ZTI4MjcyLTk5ZWYtNDBmOC1hNjM1LTRhMTgyODc4ZjQ5ZiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg1MDEyMDYyfQ.Mpf047_zweLRDzSLZjjePB5EieHI50pUuSqgLKWsH0Y
                refresh_token: LQgQuH8rdUfM5EEX3L72Jmfv
                user:
                  id: cus_UkLWZg9DAJ
                  email: test@example.com
                  first_name: Lorri
                  last_name: Keebler
                  phone:
                  accepts_email_marketing: false
                  full_name: Lorri Keebler
                  available_store_credit_total: '0'
                  display_available_store_credit_total: "$0.00"
                  addresses: []
                  default_billing_address:
                  default_shipping_address:
                  newsletter_subscriber:
                  customer_groups: []
              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:
              oneOf:
              - title: EmailPasswordLogin
                description: Built-in email/password authentication (default when
                  `provider` is omitted).
                type: object
                properties:
                  provider:
                    type: string
                    enum:
                    - email
                    default: email
                  email:
                    type: string
                    format: email
                    example: customer@example.com
                  password:
                    type: string
                    example: password123
                required:
                - email
                - password
              - title: ProviderLogin
                description: |
                  Provider-dispatched login. The `provider` key selects a configured
                  authentication provider; the remaining fields are forwarded to it.
                  Required fields depend on the provider — see
                  [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).
                type: object
                properties:
                  provider:
                    type: string
                    example: auth0
                    description: Registered provider key (anything other than `email`).
                    not:
                      enum:
                      - email
                required:
                - provider
                additionalProperties: true
  "/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.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImMyOWVjYzMyLWM2OWYtNDc0MC1hZWMxLTAwYmI1MjAwMmM4YiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg1MDEyMDYzfQ.hPY384l3tHxqKb6PPNBFa9tDeoeOBCp6sC175Q80jgs
                refresh_token: Whgj8rch8LakTYo8Aa4THTCX
                user:
                  id: cus_UkLWZg9DAJ
                  email: test@example.com
                  first_name: Sharlene
                  last_name: Zieme
                  phone:
                  accepts_email_marketing: false
                  full_name: Sharlene Zieme
                  available_store_credit_total: '0'
                  display_available_store_credit_total: "$0.00"
                  addresses: []
                  default_billing_address:
                  default_shipping_address:
                  newsletter_subscriber:
                  customer_groups: []
              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: []
      description: Revokes the submitted refresh token. The refresh token itself is
        the credential — no Authorization header is required, so a client with an
        expired access JWT can still log 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
      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/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.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImNmMWJmMTNjLTNmMjEtNGFlYy05MGM1LWVkOTViMjNjZGU1YyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg1MDEyMDc3fQ.3r4DoE_bzjyFXWDxwIbornisqHBM6tzQ7eqW-zYEUtM
                refresh_token: h2NQpqVqBVhgNYoMBQ4wDChM
                user:
                  id: cus_UkLWZg9DAJ
                  email: customer@example.com
                  first_name: Joelle
                  last_name: Feil
                  phone:
                  accepts_email_marketing: false
                  full_name: Joelle Feil
                  available_store_credit_total: '0'
                  display_available_store_credit_total: "$0.00"
                  addresses: []
                  default_billing_address:
                  default_shipping_address:
                  newsletter_subscriber:
                  customer_groups: []
              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/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_3
                  permalink: taxonomy-3
                  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_3
                  permalink: taxonomy-3/taxon-3
                  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_4
                  permalink: taxonomy-3/taxon-3/taxon-4
                  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_12
                permalink: taxonomy-9/taxon-12
                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/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 1524935
                  slug: product-1524935
                  meta_title:
                  meta_description:
                  meta_keywords:
                  variant_count: 1
                  available_on:
                  preorder_ships_at:
                  purchasable: true
                  preorder: false
                  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 1533120
                  slug: product-1533120
                  meta_title:
                  meta_description:
                  meta_keywords:
                  variant_count: 0
                  available_on:
                  preorder_ships_at:
                  purchasable: true
                  preorder: false
                  in_stock: false
                  backorderable: true
                  available: true
                  description: Minima error distinctio ducimus quas modi. Veniam beatae
                    adipisci assumenda eveniet voluptatibus. Voluptate accusamus natus
                    non reiciendis doloribus distinctio temporibus nam. Voluptates
                    eaque soluta corrupti quae ex dicta. Voluptatem laudantium dolorum
                    vel laborum sequi dicta. Perferendis consequuntur tempore quibusdam
                    eligendi repellat. Eum qui quae repellendus officiis dolorum culpa.
                  description_html: |-
                    Minima error distinctio ducimus quas modi. Veniam beatae adipisci assumenda eveniet voluptatibus. Voluptate accusamus natus non reiciendis doloribus distinctio temporibus nam. Voluptates eaque soluta corrupti quae ex dicta.
                    Voluptatem laudantium dolorum vel laborum sequi dicta. Perferendis consequuntur tempore quibusdam eligendi repellat. Eum qui quae repellendus officiis dolorum culpa.
                  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 1809191
                slug: product-1809191
                meta_title:
                meta_description:
                meta_keywords:
                variant_count: 1
                available_on:
                preorder_ships_at:
                purchasable: true
                preorder: false
                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-07-10T19:41:57Z'
              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:
                id:
                default_sort: manual
                total_count: 2
                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-27/taxon-34/shirts
                    count: 2
                sort_options:
                - id: manual
                - id: best_selling
                - id: price
                - id: "-price"
                - id: "-available_on"
                - id: available_on
                - id: name
                - id: "-name"
              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/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:
                  channel_id: ch_UkLWZg9DAJ
                  number: R747370910
                  token: KL2exoBuzKh24EVAArgsr92gKcehgXAfwaK
                  email: eunice@leschwalsh.biz
                  customer_note:
                  currency: USD
                  locale: en
                  total_quantity: 1
                  warnings: []
                  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"
                  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
                    preorder: false
                    preorder_ships_at:
                    quantity: 1
                    currency: USD
                    name: Product 921732
                    slug: product-921732
                    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: H97804265871
                    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: Emogene Cruickshank
                      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: 107 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: 108 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:
                  channel_id: ch_UkLWZg9DAJ
                  number: R392027120
                  token: 5YfNnvaM97uFunvE7iM924om6KCqNh3oqMk
                  email: eunice@leschwalsh.biz
                  customer_note:
                  currency: USD
                  locale: en
                  total_quantity: 1
                  warnings: []
                  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"
                  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
                    preorder: false
                    preorder_ships_at:
                    quantity: 1
                    currency: USD
                    name: Product 919112
                    slug: product-919112
                    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: H34758896458
                    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: Emogene Cruickshank
                      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: 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_VqXmZF31wY
                    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:
                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:
                channel_id: ch_UkLWZg9DAJ
                number: R218346036
                token: n5eNamrTj7vLwp5d1U9x854eMiL19r4q71U
                email:
                customer_note:
                currency: USD
                locale: en
                total_quantity: 0
                warnings: []
                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"
                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:
                channel_id: ch_UkLWZg9DAJ
                number: R050861879
                token: gPtWcdxxCHpWHUqNBmbAtAtbsioYp6amXwu
                email: phyliss@shanahan.co.uk
                customer_note:
                currency: USD
                locale: en
                total_quantity: 0
                warnings:
                - code: line_item_removed
                  message: Product 963498 was removed because it was sold out
                  line_item_id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                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"
                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: 115 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: 116 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:
                channel_id: ch_UkLWZg9DAJ
                number: R940369961
                token: QZrARYHAJXNZFCh63A6LiUDS5Q7YeA2H5rZ
                email: leida_lind@pfeffer.info
                customer_note: Leave at door
                currency: USD
                locale: en
                total_quantity: 1
                warnings: []
                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"
                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
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 97539
                  slug: product-97539
                  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: H31836788241
                  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: Keeley Skiles
                    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: 119 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: 120 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 and possession of the cart's token
        (x-spree-token) — the token authorizes claiming 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.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: x-spree-token
        in: header
        required: true
        description: Cart token
        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:
                channel_id: ch_UkLWZg9DAJ
                number: R399625921
                token: TDadX58HdfjSGineeB9cHshgd5ZDZEYqpWh
                email: keiko_stark@beahan.name
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                warnings: []
                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"
                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
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 995969
                  slug: product-995969
                  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: H18212968266
                  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: Rubye Gusikowski
                    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: 125 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: 126 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"
        '403':
          description: forbidden - cart token missing or does not match
          content:
            application/json:
              example:
                error:
                  code: access_denied
                  message: You are not authorized to access this page.
              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: R106523615
                email: jacqueline@eichmannbernier.biz
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                fulfillment_status: backorder
                payment_status: paid
                completed_at: '2026-07-25T19:41:09.090Z'
                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"
                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
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 1025278
                  slug: product-1025278
                  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: H04719635845
                  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: Sidney Carroll
                    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-c33567c055af
                  number: P40KTO0F
                  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: 137 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: 138 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/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:
                channel_id: ch_UkLWZg9DAJ
                number: R928002715
                token: L5prV5kAroDMaNZ2EknMFDwcygexRz4zXDQ
                email: laquita_graham@pollich.biz
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                warnings: []
                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"
                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
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 1218077
                  slug: product-1218077
                  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: H83691313514
                  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: Yolando Heller
                    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: 189 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: 190 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:
                channel_id: ch_UkLWZg9DAJ
                number: R920678008
                token: hgQA61MpbkxakNNon1gAu71XE1VM1vFuTvA
                email: jeanna@rolfsonlabadie.name
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                warnings: []
                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"
                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
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 1231174
                  slug: product-1231174
                  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: H78674840337
                  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: Leonel Muller
                    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: 197 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: 198 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:
                channel_id: ch_UkLWZg9DAJ
                number: R146081501
                token: aainvU5HCjMBZVFJydWMvo1AbrrzvwCP8pV
                email: debora@bahringer.us
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                warnings: []
                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"
                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
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 1256298
                  slug: product-1256298
                  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: H45408931001
                  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: Kimbra Ritchie
                    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: 205 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: 206 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:
                channel_id: ch_UkLWZg9DAJ
                number: R770266035
                token: wXFSUSKVkoPHm249TJ7R7mrXugs4vn8eneL
                email: elanor@quitzon.com
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                warnings: []
                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"
                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
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 1271723
                  slug: product-1271723
                  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: H93733158647
                  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: Sasha Effertz
                    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-20260725194128535812
                  number: PIQ6KHDS
                  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: 213 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: 214 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:
                channel_id: ch_UkLWZg9DAJ
                number: R818170564
                token: s3xYyqrME8qD3gho4sducCd535KMwKZCZWe
                email: beverly@huel.info
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                warnings: []
                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"
                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
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 1311850
                  slug: product-1311850
                  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: H99882305400
                  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: Markus Bechtelar
                    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-20260725194131124623
                  number: PZB5XQ18
                  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: 229 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: 230 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/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:
                channel_id: ch_UkLWZg9DAJ
                number: R733456622
                token: Fvbskuym7JjYCif4YiK3ZmPem9tXwBxsGVT
                email: vanessa@cronin.com
                customer_note:
                currency: USD
                locale: en
                total_quantity: 2
                warnings: []
                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"
                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
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 1348379
                  slug: product-1348379
                  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
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 1355524
                  slug: product-1355524
                  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: 244 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:
                channel_id: ch_UkLWZg9DAJ
                number: R843149651
                token: XhP8s6PLVGXsyuuGyEzR3kjbb5NP27eiam6
                email: amy_daniel@quitzon.info
                customer_note:
                currency: USD
                locale: en
                total_quantity: 0
                warnings: []
                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"
                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
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 1383196
                  slug: product-1383196
                  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: 253 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:
                channel_id: ch_UkLWZg9DAJ
                number: R725723396
                token: BKVjbAoa8GVS68wVEkU5hL74Dy9FCHfFFUX
                email: emely@kulas.info
                customer_note:
                currency: USD
                locale: en
                total_quantity: 0
                warnings: []
                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"
                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: 256 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/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_635c810d2ee1b5d41b126712
                external_data:
                  client_secret: bogus_secret_b3a9bdfd05316696
                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_761185063658b3880fffba37
                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_60fab7e3b0c145ed466428ec
                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_78fec2996c71cd0663195e1e
                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/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: P5DAWO0Q
                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/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:
                channel_id: ch_UkLWZg9DAJ
                number: R409425140
                token: xswvgfnoez7AqFEdUxbDamrfZFqgB7r6oMU
                email: bernita.quigley@skiles.co.uk
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                warnings: []
                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"
                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
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 2005982
                  slug: product-2005982
                  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: H81505158386
                  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: Silvia Hermann
                    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-20260725194202800328
                  number: PRDKBYS4
                  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: 340 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: 341 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:
                channel_id: ch_UkLWZg9DAJ
                number: R001123443
                token: vTEPVBXb5hYFoCsJ8xZLBv2mmwTzQc8uq5i
                email: don_nolan@priceking.us
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                warnings: []
                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"
                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
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 2022312
                  slug: product-2022312
                  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: H84545543277
                  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: Dione Turner
                    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: 348 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: 349 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/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: R984698608
                email: guest@example.com
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                fulfillment_status:
                payment_status:
                completed_at: '2026-07-25T19:41:44.353Z'
                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"
                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
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 1427424
                  slug: product-1427424
                  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: H46248291504
                  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: Yulanda Cassin
                    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: 276 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: 277 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/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: 78 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: 77 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: 76 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: 90 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: 96 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/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/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: R738167381
                  email: zelma_zboncak@runolfsdottir.us
                  customer_note:
                  currency: USD
                  locale: en
                  total_quantity: 1
                  fulfillment_status:
                  payment_status:
                  completed_at: '2026-07-25T19:41:18.090Z'
                  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"
                  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
                    preorder: false
                    preorder_ships_at:
                    quantity: 1
                    currency: USD
                    name: Product 1114844
                    slug: product-1114844
                    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: H45537721707
                    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: Lanette Smith
                      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:
                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: R030998792
                email: luciano@jacobs.co.uk
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                fulfillment_status:
                payment_status:
                completed_at: '2026-07-25T19:41:18.787Z'
                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"
                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
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 1133247
                  slug: product-1133247
                  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: H18740531973
                  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: Marcelo Lehner
                    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: 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: false
                  state_name: New York
                shipping_address:
                  id: addr_VqXmZF31wY
                  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: 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.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjBiNDk1ZTBmLTRhZmQtNDY1Zi1hMTA0LTU2NzdkZGRhN2U2ZiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg1MDEyMDgwfQ.XBJaPkz-mXn6KzhhDNOkzBRZDqEV6WGKR3sDC8vtbP0
                refresh_token: Rwa2AmXx3wLhcxiPjH4wxbjT
                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:
                  newsletter_subscriber:
                    id: sub_UkLWZg9DAJ
                    email: newuser@example.com
                    created_at: '2026-07-25T19:41:19.980Z'
                    updated_at: '2026-07-25T19:41:19.981Z'
                    verified: true
                    verified_at: '2026-07-25T19:41:19Z'
                    customer_id: cus_UkLWZg9DAJ
                  customer_groups: []
              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: rhett@williamson.name
                first_name: Sandy
                last_name: Feeney
                phone: 555-555-0199
                accepts_email_marketing: false
                full_name: Sandy Feeney
                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: 170 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: 169 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: 170 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: 169 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
                newsletter_subscriber:
                customer_groups: []
              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: clelia_keeling@schulistmayer.us
                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: 172 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: 171 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: 172 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: 171 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
                newsletter_subscriber:
                customer_groups: []
              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/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: 1B1F2EEF61F73904
                  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: DA06DD5E2C4FD382
                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/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_9cc7ff2843f3f955ed0945c3
                external_client_secret: bogus_seti_secret_b4dd83e7e5ce6b76
                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_c6eefdcf5c2bfba562121f09
                external_client_secret: seti_secret_797cb7fd657e4309568b1031
                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_c0e84c5d631133265c0e20a6
                external_client_secret: seti_secret_dee1775377b3d93f81105bfe
                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/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/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: IS42
                  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/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/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
                  default: false
                  rtl: false
                - code: en
                  name: English
                  default: true
                  rtl: false
              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
                  country_isos:
                  - US
                  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
                  country_isos:
                  - DE
                  - FR
                  supported_locales:
                  - de
                  - en
                  - fr
                  countries:
                  - iso: DE
                    iso3: IS69
                    name: Germany
                    states_required: false
                    zipcode_required: true
                  - iso: FR
                    iso3: IS70
                    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
                country_isos:
                - DE
                - FR
                supported_locales:
                - de
                - en
                - fr
                countries:
                - iso: DE
                  iso3: IS73
                  name: Germany
                  states_required: false
                  zipcode_required: true
                - iso: FR
                  iso3: IS74
                  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
                country_isos:
                - DE
                - FR
                supported_locales:
                - de
                - en
                - fr
                countries:
                - iso: DE
                  iso3: IS77
                  name: Germany
                  states_required: false
                  zipcode_required: true
                - iso: FR
                  iso3: IS78
                  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: IS82
                  name: France
                  states_required: false
                  zipcode_required: true
                - iso: DE
                  iso3: IS81
                  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/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: EH8956zxZJKiKUp36sNDESk9
                  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: 355Jp84AbFjhG5NdeggsYJg3
                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: ['items.product'],
          }, {
            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: Comma-separated associations to expand (eg items.product to get
          wishlist items with associated products)
        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: ChUn1LGAz64UyN74XjVJAMP1
                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: wDce1DpMKWt86ZDszTj55DWi
                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
                product_id: prod_gbHJdmfrXB
                wishlist_id: wl_UkLWZg9DAJ
                quantity: 1
                variant:
                  id: variant_gbHJdmfrXB
                  product_id: prod_gbHJdmfrXB
                  sku: SKU-250
                  options_text: ''
                  track_inventory: true
                  media_count: 0
                  preorder_ships_at:
                  thumbnail_url:
                  purchasable: true
                  in_stock: false
                  backorderable: true
                  preorder: false
                  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
  "/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',
            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: chas@harveywest.us
                created_at: '2026-07-25T19:41:38.859Z'
                updated_at: '2026-07-25T19:41:38.861Z'
                verified: true
                verified_at: '2026-07-25T19:41:38Z'
                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-07-25T19:41:38.924Z'
                updated_at: '2026-07-25T19:41:38.932Z'
                verified: true
                verified_at: '2026-07-25T19:41:38Z'
                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/newsletter_subscribers/{id}":
    parameters:
    - name: id
      in: path
      description: Newsletter subscriber prefix id (sub_*)
      required: true
      schema:
        type: string
    delete:
      summary: Unsubscribe from the newsletter
      tags:
      - Newsletter Subscribers
      security:
      - api_key: []
      description: |
        Destroys the newsletter subscription, firing the `newsletter_subscriber.deleted`
        lifecycle event. Two authorization paths are accepted:

        - **Unsubscribe token** in the `?token=` query param — bearer delivered to the
          subscriber by email (the link in an unsubscribe message). The token is
          cryptographically signed and is cross-checked against the `:id` in the URL —
          tampering with either is rejected. To request such an email be sent, call the
          collection action `POST /newsletter_subscribers/request_unsubscribe` with the
          subscriber's email in the body.
        - **JWT bearer** for the logged-in customer who owns the subscription. No `token`
          query param is needed in this path.

        All failure modes return a generic `invalid_token` 422.
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        description: Optional Bearer JWT — alternative to the `token` query param
        schema:
          type: string
      - name: token
        in: query
        required: false
        description: Unsubscribe token delivered to the subscriber by email (e.g.
          the link in an unsubscribe message).
        schema:
          type: string
      responses:
        '204':
          description: unsubscribed via JWT (owner)
        '422':
          description: JWT-authenticated, subscriber on a different store
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: Newsletter unsubscribe token is invalid or has expired.
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/newsletter_subscribers/request_unsubscribe":
    post:
      summary: Request an unsubscribe token
      tags:
      - Newsletter Subscribers
      security:
      - api_key: []
      description: |
        Publishes a `newsletter_subscriber.unsubscribe_requested` event carrying an unsubscribe token in the payload.
        Always returns 202 Accepted to prevent email enumeration.
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '202':
          description: returns accepted even when email is missing
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  example: subscriber@example.com
                redirect_url:
                  type: string
                  format: uri
                  description: Storefront URL the unsubscribe token should be appended
                    to in the resulting email. Silently dropped from the event payload
                    if outside the store's allowed origins.
  "/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-432f576a-3ff5-4dd3-a07d-1ee90aa4eda8
                  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/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/channel":
    get:
      summary: Get the current channel
      tags:
      - Channel
      security:
      - api_key: []
      description: Returns the channel this request resolved to (key binding → X-Spree-Channel
        header → store default), including the resolved storefront access posture.
        Reachable before authentication so gated storefronts can render a sign-in
        wall.
      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 channel = await client.channel.get()

          if (channel.storefront_access === 'login_required') {
            // render a sign-in wall before any catalog UI
          }
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: X-Spree-Channel
        in: header
        required: false
        description: Channel code or prefixed ID to resolve. When the API key is channel-bound,
          a value naming a different channel is rejected with 422 channel_mismatch;
          a value matching the bound channel is accepted.
        schema:
          type: string
      responses:
        '200':
          description: channel found
          content:
            application/json:
              example:
                id: ch_gbHJdmfrXB
                name: Wholesale
                code: wholesale
                active: true
                default: false
                storefront_access: login_required
                guest_checkout: false
              schema:
                "$ref": "#/components/schemas/Channel"
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: Valid API key required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
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
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
    ImportSchemaField:
      type: object
      description: A canonical column of an import type, including per-store custom
        field columns
      properties:
        name:
          type: string
          description: Canonical field name used in mappings
          example: slug
        label:
          type: string
          description: Human-readable label
          example: Slug
        required:
          type: boolean
          description: Whether the field must be mapped before processing
      required:
      - name
      - label
      - required
    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
    AdminUserStore:
      type: object
      description: A store the staff member can access through a role assignment
      properties:
        id:
          type: string
          description: Prefixed store ID
          example: store_abc123
        name:
          type: string
          description: Store name
          example: My Store
        code:
          type: string
          description: Store code
          example: my-store
      required:
      - id
      - name
      - code
    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
        channel_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
        warnings:
          type: array
          items:
            "$ref": "#/components/schemas/CartWarning"
        item_total:
          type: string
          nullable: true
        display_item_total:
          type: string
          nullable: true
        adjustment_total:
          type: string
          nullable: true
        display_adjustment_total:
          type: string
          nullable: true
        discount_total:
          type: string
          nullable: true
        display_discount_total:
          type: string
          nullable: true
        tax_total:
          type: string
          nullable: true
        display_tax_total:
          type: string
          nullable: true
        included_tax_total:
          type: string
          nullable: true
        display_included_tax_total:
          type: string
          nullable: true
        additional_tax_total:
          type: string
          nullable: true
        display_additional_tax_total:
          type: string
          nullable: true
        total:
          type: string
          nullable: true
        display_total:
          type: string
          nullable: true
        gift_card_total:
          type: string
          nullable: true
        display_gift_card_total:
          type: string
          nullable: true
        amount_due:
          type: string
          nullable: true
        display_amount_due:
          type: string
          nullable: true
        delivery_total:
          type: string
          nullable: true
        display_delivery_total:
          type: string
          nullable: true
        store_credit_total:
          type: string
          nullable: true
        display_store_credit_total:
          type: string
          nullable: true
        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
      - channel_id
      - number
      - token
      - email
      - customer_note
      - currency
      - locale
      - total_quantity
      - warnings
      - 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
      - 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
        default:
          type: boolean
        storefront_access:
          type: string
        guest_checkout:
          type: boolean
      required:
      - id
      - name
      - code
      - active
      - default
      - storefront_access
      - guest_checkout
      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
    CustomerGroup:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required:
      - id
      - name
      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
        newsletter_subscriber:
          allOf:
          - "$ref": "#/components/schemas/NewsletterSubscriber"
          nullable: true
        customer_groups:
          type: array
          items:
            "$ref": "#/components/schemas/CustomerGroup"
      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
      - newsletter_subscriber
      - customer_groups
      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
          nullable: true
        display_amount:
          type: string
          nullable: true
      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
          nullable: true
        display_cost:
          type: string
          nullable: true
        total:
          type: string
          nullable: true
        display_total:
          type: string
          nullable: true
        discount_total:
          type: string
          nullable: true
        display_discount_total:
          type: string
          nullable: true
        additional_tax_total:
          type: string
          nullable: true
        display_additional_tax_total:
          type: string
          nullable: true
        included_tax_total:
          type: string
          nullable: true
        display_included_tax_total:
          type: string
          nullable: true
        tax_total:
          type: string
          nullable: true
        display_tax_total:
          type: string
          nullable: true
        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
          nullable: true
        amount_used:
          type: string
          nullable: true
        amount_authorized:
          type: string
          nullable: true
        amount_remaining:
          type: string
          nullable: true
        display_amount:
          type: string
          nullable: true
        display_amount_used:
          type: string
          nullable: true
        display_amount_remaining:
          type: string
          nullable: true
        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
        preorder:
          type: boolean
        preorder_ships_at:
          type: string
          nullable: true
        quantity:
          type: number
        currency:
          type: string
        name:
          type: string
        slug:
          type: string
        options_text:
          type: string
        price:
          type: string
          nullable: true
        display_price:
          type: string
          nullable: true
        total:
          type: string
          nullable: true
        display_total:
          type: string
          nullable: true
        adjustment_total:
          type: string
          nullable: true
        display_adjustment_total:
          type: string
          nullable: true
        additional_tax_total:
          type: string
          nullable: true
        display_additional_tax_total:
          type: string
          nullable: true
        included_tax_total:
          type: string
          nullable: true
        display_included_tax_total:
          type: string
          nullable: true
        discount_total:
          type: string
          nullable: true
        display_discount_total:
          type: string
          nullable: true
        pre_tax_amount:
          type: string
          nullable: true
        display_pre_tax_amount:
          type: string
          nullable: true
        discounted_amount:
          type: string
          nullable: true
        display_discounted_amount:
          type: string
          nullable: true
        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
      - preorder
      - preorder_ships_at
      - 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
        default:
          type: boolean
        rtl:
          type: boolean
      required:
      - code
      - name
      - default
      - rtl
      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
        country_isos:
          type: array
          items:
            type: string
        supported_locales:
          type: array
          items:
            type: string
        countries:
          type: array
          items:
            "$ref": "#/components/schemas/Country"
      required:
      - id
      - name
      - currency
      - default_locale
      - tax_inclusive
      - default
      - country_isos
      - 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
        fulfillment_status:
          type: string
          nullable: true
        payment_status:
          type: string
          nullable: true
        completed_at:
          type: string
          nullable: true
        item_total:
          type: string
          nullable: true
        display_item_total:
          type: string
          nullable: true
        adjustment_total:
          type: string
          nullable: true
        display_adjustment_total:
          type: string
          nullable: true
        discount_total:
          type: string
          nullable: true
        display_discount_total:
          type: string
          nullable: true
        tax_total:
          type: string
          nullable: true
        display_tax_total:
          type: string
          nullable: true
        included_tax_total:
          type: string
          nullable: true
        display_included_tax_total:
          type: string
          nullable: true
        additional_tax_total:
          type: string
          nullable: true
        display_additional_tax_total:
          type: string
          nullable: true
        total:
          type: string
          nullable: true
        display_total:
          type: string
          nullable: true
        gift_card_total:
          type: string
          nullable: true
        display_gift_card_total:
          type: string
          nullable: true
        amount_due:
          type: string
          nullable: true
        display_amount_due:
          type: string
          nullable: true
        delivery_total:
          type: string
          nullable: true
        display_delivery_total:
          type: string
          nullable: true
        store_credit_total:
          type: string
          nullable: true
        display_store_credit_total:
          type: string
          nullable: true
        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
      - fulfillment_status
      - payment_status
      - completed_at
      - 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
      - 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
          nullable: true
        display_amount:
          type: string
          nullable: true
        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
    ProductFilterAvailabilityOption:
      type: object
      properties:
        id:
          type: string
          enum:
          - in_stock
          - out_of_stock
        count:
          type: number
      required:
      - id
      - count
      x-typelizer: true
    ProductFilterAvailability:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - availability
        options:
          type: array
          items:
            "$ref": "#/components/schemas/ProductFilterAvailabilityOption"
      required:
      - id
      - type
      - options
      x-typelizer: true
    ProductFilterCategoryOption:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        permalink:
          type: string
        count:
          type: number
      required:
      - id
      - name
      - permalink
      - count
      x-typelizer: true
    ProductFilterCategory:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - category
        options:
          type: array
          items:
            "$ref": "#/components/schemas/ProductFilterCategoryOption"
      required:
      - id
      - type
      - options
      x-typelizer: true
    ProductFilterOption:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - option
        name:
          type: string
        label:
          type: string
        kind:
          type: string
        options:
          type: array
          items:
            "$ref": "#/components/schemas/ProductFilterOptionValue"
      required:
      - id
      - type
      - name
      - label
      - kind
      - options
      x-typelizer: true
    ProductFilterOptionValue:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        label:
          type: string
        position:
          type: number
        color_code:
          type: string
          nullable: true
        image_url:
          type: string
          nullable: true
        count:
          type: number
      required:
      - id
      - name
      - label
      - position
      - color_code
      - image_url
      - count
      x-typelizer: true
    ProductFilterPriceRange:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - price_range
        min:
          type: number
        max:
          type: number
        currency:
          type: string
      required:
      - id
      - type
      - min
      - max
      - currency
      x-typelizer: true
    ProductFilterSortOption:
      type: object
      properties:
        id:
          type: string
      required:
      - id
      x-typelizer: true
    ProductFilters:
      type: object
      properties:
        id:
          type: string
        default_sort:
          type: string
        total_count:
          type: number
        filters:
          type: object
        sort_options:
          type: array
          items:
            "$ref": "#/components/schemas/ProductFilterSortOption"
      required:
      - id
      - default_sort
      - total_count
      - filters
      - sort_options
      x-typelizer: true
    ProductPublication:
      type: object
      properties:
        id:
          type: string
        published_at:
          type: string
          nullable: true
        unpublished_at:
          type: string
          nullable: true
        product_id:
          type: string
        channel_id:
          type: string
      required:
      - id
      - published_at
      - unpublished_at
      - product_id
      - channel_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
        preorder_ships_at:
          type: string
          nullable: true
        purchasable:
          type: boolean
        preorder:
          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"
        option_values:
          type: array
          items:
            "$ref": "#/components/schemas/OptionValue"
        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
      - preorder_ships_at
      - purchasable
      - preorder
      - 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
        preorder_ships_at:
          type: string
          nullable: true
        thumbnail_url:
          type: string
          nullable: true
        purchasable:
          type: boolean
        in_stock:
          type: boolean
        backorderable:
          type: boolean
        preorder:
          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
      - preorder_ships_at
      - thumbnail_url
      - purchasable
      - in_stock
      - backorderable
      - preorder
      - weight
      - height
      - width
      - depth
      - price
      - original_price
      - option_values
      x-typelizer: true
    WishlistItem:
      type: object
      properties:
        id:
          type: string
        variant_id:
          type: string
        product_id:
          type: string
        wishlist_id:
          type: string
        quantity:
          type: number
        variant:
          "$ref": "#/components/schemas/Variant"
        product:
          "$ref": "#/components/schemas/Product"
      required:
      - id
      - variant_id
      - product_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