---
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.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImRlZmM5YWZhLTUzOTYtNDEwYy1hZDY4LTE4YTBiN2M5MmMwMyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.ha-8UOgpGEgYAVWjEqzhLZ9LPtI6uTlsDB3We7qbrdU
                refresh_token: CxKP3VYWQzkXqrfxTmPLB446
                user:
                  id: cust_UkLWZg9DAJ
                  email: test@example.com
                  first_name: Julie
                  last_name: Bode
                  phone:
                  accepts_email_marketing: false
                  email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
                  full_name: Julie Bode
                  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.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjFmMzM5OGY2LTczZDgtNDdjNi1hNDk4LTUxNDc3MGUxYTUyNSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.Zpvl-ISrctLW34O3zJFteOf3wMDNvlymVKsbkCIfeew
                refresh_token: mWbQ77onTSsXQta8Z4SAVaTU
                user:
                  id: cust_UkLWZg9DAJ
                  email: test@example.com
                  first_name: Yuki
                  last_name: Harvey
                  phone:
                  accepts_email_marketing: false
                  email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
                  full_name: Yuki Harvey
                  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.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjdlOGI2Njc5LTBjNzYtNDQ1Mi1hMWMyLWJhY2U0MWNhN2IyMCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.grC4diUECUp8b3p6jJBHAZp_MyiSUQwA4rdQLel_zuM
                refresh_token: JNJKeT5cELhdSfb2tWHj3ctp
                user:
                  id: cust_UkLWZg9DAJ
                  email: customer@example.com
                  first_name: Lucas
                  last_name: Stiedemann
                  phone:
                  accepts_email_marketing: false
                  email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
                  full_name: Lucas Stiedemann
                  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: Catalog
                  permalink: catalog
                  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: category_3
                  permalink: catalog/category-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: category_4
                  permalink: catalog/category-3/category-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: category_12
                permalink: catalog/category-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/collections":
    get:
      summary: List collections
      tags:
      - Product Catalog
      security:
      - api_key: []
      description: Returns a paginated list of collections for the current store.
      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,permalink).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: collections found
          content:
            application/json:
              example:
                data:
                - id: coll_UkLWZg9DAJ
                  name: Summer Sale
                  permalink: summer-sale
                  position: 1
                  sort_order: manual
                  meta_title:
                  meta_description:
                  meta_keywords:
                  products_count: 1
                  description: ''
                  description_html: ''
                  image_url:
                  square_image_url:
                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/Collection"
                  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/collections/{id}":
    get:
      summary: Get a collection
      tags:
      - Product Catalog
      security:
      - api_key: []
      description: Returns a single collection by permalink or prefix ID.
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Collection permalink (e.g., summer-sale) or prefix ID (e.g.,
          coll_abc123)
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Expand associations (custom_fields)
        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: collection found by prefix ID
          content:
            application/json:
              example:
                id: coll_UkLWZg9DAJ
                name: Summer Sale
                permalink: summer-sale
                position: 1
                sort_order: manual
                meta_title:
                meta_description:
                meta_keywords:
                products_count: 1
                description: ''
                description_html: ''
                image_url:
                square_image_url:
              schema:
                "$ref": "#/components/schemas/Collection"
        '404':
          description: collection from other store not accessible
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Collection not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/collections/{collection_id}/products":
    get:
      summary: List collection products
      tags:
      - Product Catalog
      security:
      - api_key: []
      description: Products in the collection. Defaults to the collection's own sort
        order and accepts the same filters, sort, and pagination as the products endpoint.
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: collection_id
        in: path
        required: true
        description: Collection permalink or prefix ID
        schema:
          type: string
      - name: sort
        in: query
        required: false
        description: Sort order (e.g., price, -price). Defaults to the collection's
          sort_order.
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: products found
          content:
            application/json:
              example:
                data:
                - id: prod_UkLWZg9DAJ
                  name: Product 2516979
                  slug: product-2516979
                  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: Accusantium ex dicta error nemo ipsa vel eaque porro.
                    Laborum ipsam molestias iure aspernatur quos dolorem. Quia libero
                    odio nesciunt debitis eaque.
                  description_html: Accusantium ex dicta error nemo ipsa vel eaque
                    porro. Laborum ipsam molestias iure aspernatur quos dolorem. Quia
                    libero odio nesciunt debitis eaque.
                  default_variant_id: variant_UkLWZg9DAJ
                  buy_box_variant_id: variant_UkLWZg9DAJ
                  thumbnail_url:
                  tags: []
                  price:
                    id: price_UkLWZg9DAJ
                    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:
                  seller_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/Product"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
  "/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, seller, seller.policies)
        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 2989085
                  slug: product-2989085
                  meta_title:
                  meta_description:
                  meta_keywords:
                  variant_count: 2
                  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_UkLWZg9DAJ
                  buy_box_variant_id: variant_UkLWZg9DAJ
                  thumbnail_url:
                  tags: []
                  price:
                    id: price_UkLWZg9DAJ
                    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:
                  seller_id:
                - id: prod_gbHJdmfrXB
                  name: Product 2998209
                  slug: product-2998209
                  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: Quasi nostrum error iste autem recusandae consequuntur
                    consectetur. Dolorem ea officia rerum a. Asperiores et occaecati
                    laudantium deserunt modi reiciendis rem. Iste soluta tempora odit
                    voluptate cupiditate. Architecto nostrum aliquid est odit minima
                    repudiandae. Doloribus quos est in illum. Occaecati vero soluta
                    asperiores aliquam odio accusamus incidunt. Officia magnam fugiat
                    sint optio ipsa. Deserunt reiciendis aliquid architecto occaecati
                    rem maxime vero doloremque. Recusandae ipsum natus eius assumenda.
                  description_html: |-
                    Quasi nostrum error iste autem recusandae consequuntur consectetur. Dolorem ea officia rerum a. Asperiores et occaecati laudantium deserunt modi reiciendis rem. Iste soluta tempora odit voluptate cupiditate. Architecto nostrum aliquid est odit minima repudiandae.
                    Doloribus quos est in illum. Occaecati vero soluta asperiores aliquam odio accusamus incidunt. Officia magnam fugiat sint optio ipsa. Deserunt reiciendis aliquid architecto occaecati rem maxime vero doloremque. Recusandae ipsum natus eius assumenda.
                  default_variant_id: variant_EfhxLZ9ck8
                  buy_box_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:
                  seller_id:
                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 (variants, media, categories,
          option_types, prior_price, seller, seller.policies). On a marketplace, `seller`
          embeds the seller public profile and `seller.policies` adds their published
          legal documents; `seller_id` is present without either.
        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 3266885
                slug: product-3266885
                meta_title:
                meta_description:
                meta_keywords:
                variant_count: 2
                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_UkLWZg9DAJ
                buy_box_variant_id: variant_UkLWZg9DAJ
                thumbnail_url:
                tags: []
                price:
                  id: price_UkLWZg9DAJ
                  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:
                seller_id:
                prior_price:
                  id: _AXs1igzRC6
                  amount: '9.99'
                  amount_in_cents: 999
                  currency: USD
                  display_amount: "$9.99"
                  recorded_at: '2025-12-31T12:00:00Z'
              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_gbHJdmfrXB
                    name: Shirts
                    permalink: category-34/shirts
                    count: 2
                sort_options:
                - id: manual
                  label:
                - id: best_selling
                  label:
                - id: price
                  label:
                - id: "-price"
                  label:
                - id: "-available_on"
                  label:
                - id: available_on
                  label:
                - id: name
                  label:
                - id: "-name"
                  label:
              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_UkLWZg9DAJ
                  market_id: mkt_UkLWZg9DAJ
                  channel_id: ch_UkLWZg9DAJ
                  preferred_stock_location_id:
                  company_id:
                  company_name:
                  po_number_required: false
                  po_document_filename:
                  po_document_byte_size:
                  number: cart_UkLWZg9DAJ
                  token: ckMf2iQ6r5adLceTPfKVH9BP
                  email:
                  customer_note:
                  po_number:
                  currency: USD
                  locale: en
                  total_quantity: 1
                  warnings: []
                  coupon_code:
                  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: '10.0'
                  display_total: "$10.00"
                  gift_card_total: '0.0'
                  display_gift_card_total: "$0.00"
                  amount_due: '10.0'
                  display_amount_due: "$10.00"
                  delivery_total: '0.0'
                  display_delivery_total: "$0.00"
                  fee_total: '0.0'
                  display_fee_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:
                  - code: email_required
                    step: address
                    field: email
                    message: Email address is required
                  - code: ship_address_required
                    step: address
                    field: ship_address
                    message: Shipping address is required
                  - code: delivery_method_required
                    step: delivery
                    field: delivery_method
                    message: Select a delivery method for all fulfillments
                  - code: payment_required
                    step: payment
                    field: payment
                    message: Add a payment method
                  order_minimum:
                  order_minimum_shortfall:
                  below_order_minimum: false
                  freight_summary:
                  shipping_eq_billing_address: true
                  discounts: []
                  fees: []
                  items:
                  - id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    seller_id:
                    preorder: false
                    preorder_ships_at:
                    quantity: 1
                    currency: USD
                    name: Product 225715
                    slug: product-225715
                    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:
                  shipping_address:
                  payment_methods: []
                  gift_card:
                  market:
                    id: mkt_UkLWZg9DAJ
                    name: United States
                    currency: USD
                    default_locale: en
                    tax_inclusive: false
                    default: true
                    country_codes:
                    - US
                    supported_locales:
                    - en
                - id: cart_gbHJdmfrXB
                  market_id: mkt_UkLWZg9DAJ
                  channel_id: ch_UkLWZg9DAJ
                  preferred_stock_location_id:
                  company_id:
                  company_name:
                  po_number_required: false
                  po_document_filename:
                  po_document_byte_size:
                  number: cart_gbHJdmfrXB
                  token: pvLw1ZWLLQNxh1uvSPUCdSmt
                  email:
                  customer_note:
                  po_number:
                  currency: USD
                  locale: en
                  total_quantity: 1
                  warnings: []
                  coupon_code:
                  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: '10.0'
                  display_total: "$10.00"
                  gift_card_total: '0.0'
                  display_gift_card_total: "$0.00"
                  amount_due: '10.0'
                  display_amount_due: "$10.00"
                  delivery_total: '0.0'
                  display_delivery_total: "$0.00"
                  fee_total: '0.0'
                  display_fee_total: "$0.00"
                  store_credit_total: '0'
                  display_store_credit_total: "$0.00"
                  covered_by_store_credit: false
                  current_step: address
                  completed_steps: []
                  requirements:
                  - code: email_required
                    step: address
                    field: email
                    message: Email address is required
                  - code: ship_address_required
                    step: address
                    field: ship_address
                    message: Shipping address is required
                  - code: delivery_method_required
                    step: delivery
                    field: delivery_method
                    message: Select a delivery method for all fulfillments
                  - code: payment_required
                    step: payment
                    field: payment
                    message: Add a payment method
                  order_minimum:
                  order_minimum_shortfall:
                  below_order_minimum: false
                  freight_summary:
                  shipping_eq_billing_address: true
                  discounts: []
                  fees: []
                  items:
                  - id: li_gbHJdmfrXB
                    variant_id: variant_gbHJdmfrXB
                    seller_id:
                    preorder: false
                    preorder_ships_at:
                    quantity: 1
                    currency: USD
                    name: Product 2262171
                    slug: product-2262171
                    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:
                  shipping_address:
                  payment_methods: []
                  gift_card:
                  market:
                    id: mkt_UkLWZg9DAJ
                    name: United States
                    currency: USD
                    default_locale: en
                    tax_inclusive: false
                    default: true
                    country_codes:
                    - US
                    supported_locales:
                    - en
                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: mkt_UkLWZg9DAJ
                channel_id: ch_UkLWZg9DAJ
                preferred_stock_location_id:
                company_id:
                company_name:
                po_number_required: false
                po_document_filename:
                po_document_byte_size:
                number: cart_UkLWZg9DAJ
                token: jBrNbC8FSNyavqebdqu7e3uL
                email:
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 0
                warnings: []
                coupon_code:
                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"
                fee_total: '0.0'
                display_fee_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:
                - code: line_items_required
                  step: cart
                  field: line_items
                  message: Add at least one item to your cart
                - code: email_required
                  step: address
                  field: email
                  message: Email address is required
                order_minimum:
                order_minimum_shortfall:
                below_order_minimum: false
                freight_summary:
                shipping_eq_billing_address: true
                discounts: []
                fees: []
                items: []
                fulfillments: []
                payments: []
                billing_address:
                shipping_address:
                payment_methods: []
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
              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: mkt_UkLWZg9DAJ
                channel_id: ch_UkLWZg9DAJ
                preferred_stock_location_id:
                company_id:
                company_name:
                po_number_required: false
                po_document_filename:
                po_document_byte_size:
                number: cart_UkLWZg9DAJ
                token: HnnryvFFwjfx9P6ykByF4Gg2
                email:
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 0
                warnings:
                - code: line_item_removed
                  message: Product 230307 was removed because it was sold out
                  line_item_id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                coupon_code:
                item_total: '0.0'
                display_item_total: "$0.00"
                adjustment_total: '17.0'
                display_adjustment_total: "$17.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: '17.0'
                display_total: "$17.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '17.0'
                display_amount_due: "$17.00"
                delivery_total: '0.0'
                display_delivery_total: "$0.00"
                fee_total: '17.0'
                display_fee_total: "$17.00"
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                current_step: address
                completed_steps: []
                requirements:
                - code: line_items_required
                  step: cart
                  field: line_items
                  message: Add at least one item to your cart
                - code: email_required
                  step: address
                  field: email
                  message: Email address is required
                - code: payment_required
                  step: payment
                  field: payment
                  message: Add a payment method
                order_minimum:
                order_minimum_shortfall:
                below_order_minimum: false
                freight_summary:
                shipping_eq_billing_address: true
                discounts: []
                fees:
                - id: fee_UkLWZg9DAJ
                  label: Gift wrapping
                  kind: gift_wrap
                  line_item_id:
                  fulfillment_id:
                  amount: '5.0'
                  display_amount: "$5.00"
                - id: fee_gbHJdmfrXB
                  label: Import duty
                  kind: duty
                  line_item_id:
                  fulfillment_id:
                  amount: '12.0'
                  display_amount: "$12.00"
                items: []
                fulfillments: []
                payments: []
                billing_address:
                shipping_address:
                payment_methods: []
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
              schema:
                "$ref": "#/components/schemas/Cart"
        '404':
          description: cart not found
          content:
            application/json:
              example:
                error:
                  code: record_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_code: '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: mkt_UkLWZg9DAJ
                channel_id: ch_UkLWZg9DAJ
                preferred_stock_location_id:
                company_id:
                company_name:
                po_number_required: false
                po_document_filename:
                po_document_byte_size:
                number: cart_UkLWZg9DAJ
                token: PMVmxRAiLqMivU5QgJqfpQMD
                email:
                customer_note: Leave at door
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                warnings: []
                coupon_code:
                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: '10.0'
                display_total: "$10.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '10.0'
                display_amount_due: "$10.00"
                delivery_total: '0.0'
                display_delivery_total: "$0.00"
                fee_total: '0.0'
                display_fee_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:
                - code: email_required
                  step: address
                  field: email
                  message: Email address is required
                - code: delivery_method_required
                  step: delivery
                  field: delivery_method
                  message: Select a delivery method for all fulfillments
                - code: payment_required
                  step: payment
                  field: payment
                  message: Add a payment method
                order_minimum:
                order_minimum_shortfall:
                below_order_minimum: false
                freight_summary:
                shipping_eq_billing_address: true
                discounts: []
                fees: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  seller_id:
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 2313263
                  slug: product-2313263
                  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:
                shipping_address:
                payment_methods: []
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
              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_code:
                      type: string
                    state_code:
                      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_code:
                      type: string
                    state_code:
                      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: mkt_UkLWZg9DAJ
                channel_id: ch_UkLWZg9DAJ
                preferred_stock_location_id:
                company_id:
                company_name:
                po_number_required: false
                po_document_filename:
                po_document_byte_size:
                number: cart_UkLWZg9DAJ
                token: rrGvkDXx3KcQVwLVk8XiVCVk
                email: steve@tromp.com
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                warnings: []
                coupon_code:
                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: '10.0'
                display_total: "$10.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '10.0'
                display_amount_due: "$10.00"
                delivery_total: '0.0'
                display_delivery_total: "$0.00"
                fee_total: '0.0'
                display_fee_total: "$0.00"
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                current_step: delivery
                completed_steps:
                - address
                requirements:
                - code: delivery_method_required
                  step: delivery
                  field: delivery_method
                  message: Select a delivery method for all fulfillments
                - code: payment_required
                  step: payment
                  field: payment
                  message: Add a payment method
                order_minimum:
                order_minimum_shortfall:
                below_order_minimum: false
                freight_summary:
                shipping_eq_billing_address: false
                discounts: []
                fees: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  seller_id:
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 2338992
                  slug: product-2338992
                  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_gbHJdmfrXB
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 254 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: true
                  is_default_shipping: false
                  state_abbr: NY
                  country_iso: US
                  state_name: New York
                shipping_address:
                  id: addr_UkLWZg9DAJ
                  label:
                  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
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: true
                  state_abbr: NY
                  country_iso: US
                  state_name: New York
                payment_methods: []
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
              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: mkt_UkLWZg9DAJ
                withdrawal_period_ends_at:
                within_withdrawal_period: true
                cart_id: cart_UkLWZg9DAJ
                channel_id: ch_UkLWZg9DAJ
                company_id:
                company_name:
                po_document_filename:
                po_document_byte_size:
                number: R1001
                email: marvel@bruen.com
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                coupon_code:
                fulfillment_status: backorder
                payment_status: paid
                completed_at: '2026-01-15T12:00:00.000Z'
                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: '20.0'
                display_total: "$20.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '20.0'
                display_amount_due: "$20.00"
                delivery_total: '10.0'
                display_delivery_total: "$10.00"
                fee_total: '0.0'
                display_fee_total: "$0.00"
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                discounts: []
                fees: []
                items:
                - id: li_gbHJdmfrXB
                  variant_id: variant_UkLWZg9DAJ
                  seller_id:
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 2364794
                  slug: product-2364794
                  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: R1001-F1
                  tracking:
                  tracking_url:
                  pickup_point_data:
                  selected_delivery_rate_id: dr_gbHJdmfrXB
                  unpriced: false
                  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: unfulfilled
                  fulfillment_type: shipping
                  fulfilled_at:
                  delivered_at:
                  items:
                  - item_id: li_gbHJdmfrXB
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                  deliveries: []
                  delivery_method:
                    id: dm_UkLWZg9DAJ
                    name: UPS Ground 113
                    code: UPS_GROUND_130
                    estimated_transit_business_days_min:
                    estimated_transit_business_days_max:
                    digital: false
                    pickup: false
                    pickup_point: false
                  stock_location:
                    id: sloc_UkLWZg9DAJ
                    name: Deangelo Prosacco
                    address1: 1600 Pennsylvania Ave NW
                    city: Washington
                    zipcode: '20500'
                    country_code: US
                    country_name: United States
                    state_code: AL
                    state_text: AL
                    pickup_ready_in_minutes:
                    pickup_instructions:
                  delivery_rates:
                  - id: dr_gbHJdmfrXB
                    delivery_method_id: dm_UkLWZg9DAJ
                    name: UPS Ground 113
                    selected: true
                    cost: '10.0'
                    total: '10.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    carrier:
                    service_level:
                    estimated_delivery_date:
                    unpriced: false
                    freight_summary:
                    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 113
                      code: UPS_GROUND_130
                      estimated_transit_business_days_min:
                      estimated_transit_business_days_max:
                      digital: false
                      pickup: false
                      pickup_point: false
                payments:
                - id: py_UkLWZg9DAJ
                  payment_method_id: pm_UkLWZg9DAJ
                  response_code: BGS-518d4ef9738e
                  number: R1001-P1
                  status: completed
                  amount: '20.0'
                  display_amount: "$20.00"
                  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 5
                    description:
                    type: check
                    session_required: false
                    source_required: false
                billing_address:
                  id: addr_uw2YK1rnl0
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 260 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_abbr: NY
                  country_iso: US
                  state_name: New York
                shipping_address:
                  id: addr_OIJLhNcSbf
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 259 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_abbr: NY
                  country_iso: US
                  state_name: New York
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
              schema:
                "$ref": "#/components/schemas/Order"
        '422':
          description: cannot complete
          content:
            application/json:
              example:
                error:
                  code: cart_cannot_complete
                  message: '{code: "validation_failed", errors: [{code: "email_required",
                    step: "address", field: "email", message: "Email address is required"},
                    {code: "delivery_method_required", step: "delivery", field: "delivery_method",
                    message: "Select a delivery method for all fulfillments"}, {code:
                    "payment_required", step: "payment", field: "payment", message:
                    "Add a payment method"}]}'
              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: real code kept pending with eligibility warning
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id: mkt_UkLWZg9DAJ
                channel_id: ch_UkLWZg9DAJ
                preferred_stock_location_id:
                company_id:
                company_name:
                po_number_required: false
                po_document_filename:
                po_document_byte_size:
                number: cart_UkLWZg9DAJ
                token: x1oKZCt9usDGTWQZZQiL1XQ1
                email:
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                warnings:
                - code: coupon_code_not_eligible
                  message: This coupon code can't be applied to orders less than $1,000,000.00.
                coupon_code: big50
                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: '10.0'
                display_total: "$10.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '10.0'
                display_amount_due: "$10.00"
                delivery_total: '0.0'
                display_delivery_total: "$0.00"
                fee_total: '0.0'
                display_fee_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:
                - code: email_required
                  step: address
                  field: email
                  message: Email address is required
                - code: delivery_method_required
                  step: delivery
                  field: delivery_method
                  message: Select a delivery method for all fulfillments
                - code: payment_required
                  step: payment
                  field: payment
                  message: Add a payment method
                order_minimum:
                order_minimum_shortfall:
                below_order_minimum: false
                freight_summary:
                shipping_eq_billing_address: true
                discounts: []
                fees: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  seller_id:
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 2652614
                  slug: product-2652614
                  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:
                shipping_address:
                payment_methods: []
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
              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: mkt_UkLWZg9DAJ
                channel_id: ch_UkLWZg9DAJ
                preferred_stock_location_id:
                company_id:
                company_name:
                po_number_required: false
                po_document_filename:
                po_document_byte_size:
                number: cart_UkLWZg9DAJ
                token: gvr8TwNVJpxWf27uUHDj5Lj4
                email:
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                warnings: []
                coupon_code:
                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: '10.0'
                display_total: "$10.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '10.0'
                display_amount_due: "$10.00"
                delivery_total: '0.0'
                display_delivery_total: "$0.00"
                fee_total: '0.0'
                display_fee_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:
                - code: email_required
                  step: address
                  field: email
                  message: Email address is required
                - code: delivery_method_required
                  step: delivery
                  field: delivery_method
                  message: Select a delivery method for all fulfillments
                - code: payment_required
                  step: payment
                  field: payment
                  message: Add a payment method
                order_minimum:
                order_minimum_shortfall:
                below_order_minimum: false
                freight_summary:
                shipping_eq_billing_address: true
                discounts: []
                fees: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  seller_id:
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 2663461
                  slug: product-2663461
                  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:
                shipping_address:
                payment_methods: []
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
              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: mkt_UkLWZg9DAJ
                channel_id: ch_UkLWZg9DAJ
                preferred_stock_location_id:
                company_id:
                company_name:
                po_number_required: false
                po_document_filename:
                po_document_byte_size:
                number: cart_UkLWZg9DAJ
                token: KLLfFWg9T6dGonBb65hHjaZr
                email: donya@jacobsonkunze.biz
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                warnings: []
                coupon_code:
                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: '20.0'
                display_total: "$20.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '20.0'
                display_amount_due: "$20.00"
                delivery_total: '10.0'
                display_delivery_total: "$10.00"
                fee_total: '0.0'
                display_fee_total: "$0.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:
                - code: payment_required
                  step: payment
                  field: payment
                  message: Add a payment method
                order_minimum:
                order_minimum_shortfall:
                below_order_minimum: false
                freight_summary:
                shipping_eq_billing_address: false
                discounts: []
                fees: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  seller_id:
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 2688182
                  slug: product-2688182
                  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: cart_UkLWZg9DAJ-F1
                  tracking:
                  tracking_url:
                  pickup_point_data:
                  selected_delivery_rate_id: dr_gbHJdmfrXB
                  unpriced: false
                  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: unfulfilled
                  fulfillment_type: shipping
                  fulfilled_at:
                  delivered_at:
                  items:
                  - item_id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                  deliveries: []
                  delivery_method:
                    id: dm_UkLWZg9DAJ
                    name: UPS Ground 130
                    code: UPS_GROUND_148
                    estimated_transit_business_days_min:
                    estimated_transit_business_days_max:
                    digital: false
                    pickup: false
                    pickup_point: false
                  stock_location:
                    id: sloc_UkLWZg9DAJ
                    name: Monnie O'Keefe
                    address1: 1600 Pennsylvania Ave NW
                    city: Washington
                    zipcode: '20500'
                    country_code: US
                    country_name: United States
                    state_code: AL
                    state_text: AL
                    pickup_ready_in_minutes:
                    pickup_instructions:
                  delivery_rates:
                  - id: dr_gbHJdmfrXB
                    delivery_method_id: dm_UkLWZg9DAJ
                    name: UPS Ground 130
                    selected: true
                    cost: '10.0'
                    total: '10.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    carrier:
                    service_level:
                    estimated_delivery_date:
                    unpriced: false
                    freight_summary:
                    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 130
                      code: UPS_GROUND_148
                      estimated_transit_business_days_min:
                      estimated_transit_business_days_max:
                      digital: false
                      pickup: false
                      pickup_point: false
                payments: []
                billing_address:
                shipping_address:
                  id: addr_EfhxLZ9ck8
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 356 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_abbr: NY
                  country_iso: US
                  state_name: New York
                payment_methods: []
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
              schema:
                "$ref": "#/components/schemas/Cart"
        '404':
          description: delivery rate not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Delivery 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: mkt_UkLWZg9DAJ
                channel_id: ch_UkLWZg9DAJ
                preferred_stock_location_id:
                company_id:
                company_name:
                po_number_required: false
                po_document_filename:
                po_document_byte_size:
                number: cart_UkLWZg9DAJ
                token: nZjAPYSKrNaHf2ZVT6eZfNJV
                email:
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                warnings: []
                coupon_code:
                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: '10.0'
                display_total: "$10.00"
                gift_card_total: '10.0'
                display_gift_card_total: "$10.00"
                amount_due: '0.0'
                display_amount_due: "$0.00"
                delivery_total: '0.0'
                display_delivery_total: "$0.00"
                fee_total: '0.0'
                display_fee_total: "$0.00"
                store_credit_total: '10.0'
                display_store_credit_total: "-$10.00"
                covered_by_store_credit: true
                current_step: address
                completed_steps: []
                requirements:
                - code: email_required
                  step: address
                  field: email
                  message: Email address is required
                - code: delivery_method_required
                  step: delivery
                  field: delivery_method
                  message: Select a delivery method for all fulfillments
                order_minimum:
                order_minimum_shortfall:
                below_order_minimum: false
                freight_summary:
                shipping_eq_billing_address: true
                discounts: []
                fees: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  seller_id:
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 2705702
                  slug: product-2705702
                  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:
                - id: py_UkLWZg9DAJ
                  payment_method_id: pm_UkLWZg9DAJ
                  response_code: 1-SC-20260115120000000000
                  number: cart_UkLWZg9DAJ-P1
                  status: checkout
                  amount: '10.0'
                  display_amount: "$10.00"
                  source_type: store_credit
                  source_id: credit_UkLWZg9DAJ
                  source:
                    id: credit_UkLWZg9DAJ
                    amount: '10.0'
                    amount_used: '0.0'
                    amount_remaining: '10.0'
                    display_amount: "$10.00"
                    display_amount_used: "$0.00"
                    display_amount_remaining: "$10.00"
                    currency: USD
                  payment_method:
                    id: pm_UkLWZg9DAJ
                    name: Store Credit
                    description:
                    type: store_credit
                    session_required: false
                    source_required: true
                billing_address:
                shipping_address:
                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: '10.0'
                  amount_authorized: '0.0'
                  amount_remaining: '40.0'
                  display_amount: "$50.00"
                  display_amount_used: "$10.00"
                  display_amount_remaining: "$40.00"
                  expires_at:
                  redeemed_at:
                  expired: false
                  active: true
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
              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: mkt_UkLWZg9DAJ
                channel_id: ch_UkLWZg9DAJ
                preferred_stock_location_id:
                company_id:
                company_name:
                po_number_required: false
                po_document_filename:
                po_document_byte_size:
                number: cart_UkLWZg9DAJ
                token: Wgq8NrLX3TUQLroJRYWFdQd5
                email:
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                warnings: []
                coupon_code:
                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: '10.0'
                display_total: "$10.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '10.0'
                display_amount_due: "$10.00"
                delivery_total: '0.0'
                display_delivery_total: "$0.00"
                fee_total: '0.0'
                display_fee_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:
                - code: email_required
                  step: address
                  field: email
                  message: Email address is required
                - code: delivery_method_required
                  step: delivery
                  field: delivery_method
                  message: Select a delivery method for all fulfillments
                - code: payment_required
                  step: payment
                  field: payment
                  message: Add a payment method
                order_minimum:
                order_minimum_shortfall:
                below_order_minimum: false
                freight_summary:
                shipping_eq_billing_address: true
                discounts: []
                fees: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  seller_id:
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 2749569
                  slug: product-2749569
                  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:
                - id: py_UkLWZg9DAJ
                  payment_method_id: pm_UkLWZg9DAJ
                  response_code: 1-SC-20260115120000000000
                  number: cart_UkLWZg9DAJ-P1
                  status: invalid
                  amount: '10.0'
                  display_amount: "$10.00"
                  source_type: store_credit
                  source_id: credit_UkLWZg9DAJ
                  source:
                    id: credit_UkLWZg9DAJ
                    amount: '10.0'
                    amount_used: '0.0'
                    amount_remaining: '10.0'
                    display_amount: "$10.00"
                    display_amount_used: "$0.00"
                    display_amount_remaining: "$10.00"
                    currency: USD
                  payment_method:
                    id: pm_UkLWZg9DAJ
                    name: Store Credit
                    description:
                    type: store_credit
                    session_required: false
                    source_required: true
                billing_address:
                shipping_address:
                payment_methods: []
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
              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: mkt_UkLWZg9DAJ
                channel_id: ch_UkLWZg9DAJ
                preferred_stock_location_id:
                company_id:
                company_name:
                po_number_required: false
                po_document_filename:
                po_document_byte_size:
                number: cart_UkLWZg9DAJ
                token: d12LXVnL3KtzGjXePqRawnPc
                email:
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 2
                warnings:
                - code: delivery_unavailable
                  message: Product 27763 cannot be delivered to the selected address
                  line_item_id: li_UkLWZg9DAJ
                - code: delivery_unavailable
                  message: Product 278298 cannot be delivered to the selected address
                  line_item_id: li_gbHJdmfrXB
                coupon_code:
                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"
                fee_total: '0.0'
                display_fee_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:
                - code: email_required
                  step: address
                  field: email
                  message: Email address is required
                - code: delivery_method_required
                  step: delivery
                  field: delivery_method
                  message: Select a delivery method for all fulfillments
                - code: payment_required
                  step: payment
                  field: payment
                  message: Add a payment method
                order_minimum:
                order_minimum_shortfall:
                below_order_minimum: false
                freight_summary:
                shipping_eq_billing_address: true
                discounts: []
                fees: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  seller_id:
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 27763
                  slug: product-27763
                  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
                  seller_id:
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 278298
                  slug: product-278298
                  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:
                shipping_address:
                payment_methods: []
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
              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"
        '422':
          description: rejected by a store rule
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Quantity You can order at most 10 of this item.
                  details:
                    quantity:
                    - You can order at most 10 of this item.
              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: quantity change rejected, reported in warnings
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id: mkt_UkLWZg9DAJ
                channel_id: ch_UkLWZg9DAJ
                preferred_stock_location_id:
                company_id:
                company_name:
                po_number_required: false
                po_document_filename:
                po_document_byte_size:
                number: cart_UkLWZg9DAJ
                token: Yq5XuZqq7KS7y7n2dMsChnZM
                email:
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                warnings:
                - code: purchase_limit_exceeded
                  message: Quantity You can order at most 10 of this item.
                  variant_id: variant_UkLWZg9DAJ
                  item_index: 0
                coupon_code:
                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: '10.0'
                display_total: "$10.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '10.0'
                display_amount_due: "$10.00"
                delivery_total: '0.0'
                display_delivery_total: "$0.00"
                fee_total: '0.0'
                display_fee_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:
                - code: email_required
                  step: address
                  field: email
                  message: Email address is required
                - code: delivery_method_required
                  step: delivery
                  field: delivery_method
                  message: Select a delivery method for all fulfillments
                - code: payment_required
                  step: payment
                  field: payment
                  message: Add a payment method
                order_minimum:
                order_minimum_shortfall:
                below_order_minimum: false
                freight_summary:
                shipping_eq_billing_address: true
                discounts: []
                fees: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  seller_id:
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 2849165
                  slug: product-2849165
                  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:
                shipping_address:
                payment_methods: []
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
              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: mkt_UkLWZg9DAJ
                channel_id: ch_UkLWZg9DAJ
                preferred_stock_location_id:
                company_id:
                company_name:
                po_number_required: false
                po_document_filename:
                po_document_byte_size:
                number: cart_UkLWZg9DAJ
                token: arTvbVzmU1krWKLbRnWDZ3cL
                email:
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 0
                warnings: []
                coupon_code:
                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"
                fee_total: '0.0'
                display_fee_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:
                - code: line_items_required
                  step: cart
                  field: line_items
                  message: Add at least one item to your cart
                - code: email_required
                  step: address
                  field: email
                  message: Email address is required
                order_minimum:
                order_minimum_shortfall:
                below_order_minimum: false
                freight_summary:
                shipping_eq_billing_address: true
                discounts: []
                fees: []
                items: []
                fulfillments: []
                payments: []
                billing_address:
                shipping_address:
                payment_methods: []
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
              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_208a8eb2883f955fd5c07616
                external_data:
                  client_secret: bogus_secret_a8b3afe691c933c1
                customer_external_id:
                expires_at:
                amount: '10.0'
                payment_method_id: pm_UkLWZg9DAJ
                order_id: cart_UkLWZg9DAJ
                cart_id: cart_UkLWZg9DAJ
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Credit Card 121
                  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_96d0ebf0a4300304c930f3c0
                external_data:
                  client_secret: secret_123
                customer_external_id:
                expires_at:
                amount: '10.0'
                payment_method_id: pm_UkLWZg9DAJ
                order_id: cart_UkLWZg9DAJ
                cart_id: cart_UkLWZg9DAJ
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Credit Card 122
                  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_8a53bedc6c12205d0e31f231
                external_data:
                  client_secret: secret_123
                customer_external_id:
                expires_at:
                amount: '50.0'
                payment_method_id: pm_UkLWZg9DAJ
                order_id: cart_UkLWZg9DAJ
                cart_id: cart_UkLWZg9DAJ
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Credit Card 124
                  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_f6de6a6c7dddf8f63c45a3f0
                external_data:
                  client_secret: secret_123
                customer_external_id:
                expires_at:
                amount: '10.0'
                payment_method_id: pm_UkLWZg9DAJ
                order_id: cart_UkLWZg9DAJ
                cart_id: cart_UkLWZg9DAJ
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Credit Card 125
                  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: cart_UkLWZg9DAJ-P1
                status: checkout
                amount: '10.0'
                display_amount: "$10.00"
                source_type:
                source_id:
                source:
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Check 6
                  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: mkt_UkLWZg9DAJ
                channel_id: ch_UkLWZg9DAJ
                preferred_stock_location_id:
                company_id:
                company_name:
                po_number_required: false
                po_document_filename:
                po_document_byte_size:
                number: cart_UkLWZg9DAJ
                token: acfBZtWemHae74Y3g18LQg1f
                email:
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                warnings: []
                coupon_code:
                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: '10.0'
                display_total: "$10.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"
                fee_total: '0.0'
                display_fee_total: "$0.00"
                store_credit_total: '10.0'
                display_store_credit_total: "-$10.00"
                covered_by_store_credit: true
                current_step: address
                completed_steps: []
                requirements:
                - code: email_required
                  step: address
                  field: email
                  message: Email address is required
                - code: delivery_method_required
                  step: delivery
                  field: delivery_method
                  message: Select a delivery method for all fulfillments
                order_minimum:
                order_minimum_shortfall:
                below_order_minimum: false
                freight_summary:
                shipping_eq_billing_address: true
                discounts: []
                fees: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  seller_id:
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 3469789
                  slug: product-3469789
                  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:
                - id: py_UkLWZg9DAJ
                  payment_method_id: pm_UkLWZg9DAJ
                  response_code: 1-SC-20260115120000000000
                  number: cart_UkLWZg9DAJ-P1
                  status: checkout
                  amount: '10.0'
                  display_amount: "$10.00"
                  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 5
                    description: Store Credit
                    type: store_credit
                    session_required: false
                    source_required: true
                billing_address:
                shipping_address:
                payment_methods:
                - id: pm_UkLWZg9DAJ
                  name: Store Credit 5
                  description: Store Credit
                  type: store_credit
                  session_required: false
                  source_required: true
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
              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: mkt_UkLWZg9DAJ
                channel_id: ch_UkLWZg9DAJ
                preferred_stock_location_id:
                company_id:
                company_name:
                po_number_required: false
                po_document_filename:
                po_document_byte_size:
                number: cart_UkLWZg9DAJ
                token: BHWevnp2PQxC1jSWU3ZFLejT
                email:
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                warnings: []
                coupon_code:
                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: '10.0'
                display_total: "$10.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '10.0'
                display_amount_due: "$10.00"
                delivery_total: '0.0'
                display_delivery_total: "$0.00"
                fee_total: '0.0'
                display_fee_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:
                - code: email_required
                  step: address
                  field: email
                  message: Email address is required
                - code: delivery_method_required
                  step: delivery
                  field: delivery_method
                  message: Select a delivery method for all fulfillments
                - code: payment_required
                  step: payment
                  field: payment
                  message: Add a payment method
                order_minimum:
                order_minimum_shortfall:
                below_order_minimum: false
                freight_summary:
                shipping_eq_billing_address: true
                discounts: []
                fees: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  seller_id:
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 348179
                  slug: product-348179
                  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:
                shipping_address:
                payment_methods: []
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
              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: mkt_UkLWZg9DAJ
                withdrawal_period_ends_at:
                within_withdrawal_period: true
                cart_id:
                channel_id: ch_UkLWZg9DAJ
                company_id:
                company_name:
                po_document_filename:
                po_document_byte_size:
                number: R1001
                email: guest@example.com
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                coupon_code:
                fulfillment_status:
                payment_status:
                completed_at: '2026-01-15T12:00:00.000Z'
                item_total: '10.0'
                display_item_total: "$10.00"
                adjustment_total: '12.0'
                display_adjustment_total: "$12.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: '122.0'
                display_total: "$122.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '122.0'
                display_amount_due: "$122.00"
                delivery_total: '100.0'
                display_delivery_total: "$100.00"
                fee_total: '12.0'
                display_fee_total: "$12.00"
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                discounts: []
                fees:
                - id: fee_UkLWZg9DAJ
                  label: Import duty
                  kind: duty
                  line_item_id:
                  fulfillment_id:
                  amount: '12.0'
                  display_amount: "$12.00"
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  seller_id:
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 288496
                  slug: product-288496
                  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: R1001-F1
                  tracking: U10000
                  tracking_url:
                  pickup_point_data:
                  selected_delivery_rate_id: dr_gbHJdmfrXB
                  unpriced: false
                  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: unfulfilled
                  fulfillment_type: shipping
                  fulfilled_at:
                  delivered_at:
                  items:
                  - item_id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                  deliveries:
                  - id: dlv_UkLWZg9DAJ
                    tracking_number: U10000
                    carrier:
                    carrier_name:
                    service:
                    status: pending
                    tracking_url:
                    estimated_delivery_at:
                    delivered_at:
                  delivery_method:
                    id: dm_UkLWZg9DAJ
                    name: UPS Ground 144
                    code: UPS_GROUND_162
                    estimated_transit_business_days_min:
                    estimated_transit_business_days_max:
                    digital: false
                    pickup: false
                    pickup_point: false
                  stock_location:
                    id: sloc_UkLWZg9DAJ
                    name: Thomasine Armstrong
                    address1: 1600 Pennsylvania Ave NW
                    city: Washington
                    zipcode: '20500'
                    country_code: US
                    country_name: United States
                    state_code: AL
                    state_text: AL
                    pickup_ready_in_minutes:
                    pickup_instructions:
                  delivery_rates:
                  - id: dr_gbHJdmfrXB
                    delivery_method_id: dm_UkLWZg9DAJ
                    name: UPS Ground 144
                    selected: true
                    cost: '10.0'
                    total: '10.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    carrier:
                    service_level:
                    estimated_delivery_date:
                    unpriced: false
                    freight_summary:
                    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 144
                      code: UPS_GROUND_162
                      estimated_transit_business_days_min:
                      estimated_transit_business_days_max:
                      digital: false
                      pickup: false
                      pickup_point: false
                payments: []
                billing_address:
                  id: addr_UkLWZg9DAJ
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 412 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_abbr: NY
                  country_iso: US
                  state_name: New York
                shipping_address:
                  id: addr_gbHJdmfrXB
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 413 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_abbr: NY
                  country_iso: US
                  state_name: New York
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
              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_UkLWZg9DAJ
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 218 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: true
                  state_abbr: NY
                  country_iso: US
                  state_name: New York
                - id: addr_gbHJdmfrXB
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 219 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: true
                  is_default_shipping: false
                  state_abbr: NY
                  country_iso: US
                  state_name: New York
                - id: addr_EfhxLZ9ck8
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 220 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_abbr: NY
                  country_iso: US
                  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_code: '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
                label:
                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
                country_code: US
                state_text: NY
                state_code: NY
                quick_checkout: false
                is_default_billing: false
                is_default_shipping: false
                state_abbr: NY
                country_iso: US
                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:
                    first_name:
                    - can't be blank
                    last_name:
                    - can't be blank
                    address1:
                    - can't be blank
                    city:
                    - can't be blank
                    country:
                    - can't be blank
                    postal_code:
                    - 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_code:
                  type: string
                  example: US
                  description: ISO 3166-1 alpha-2 country code (e.g., "US", "DE")
                state_code:
                  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_code
  "/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
                label:
                first_name: John
                last_name: Doe
                full_name: John Doe
                address1: 232 Lovely Street
                address2: Northwest
                postal_code: '10118'
                city: New York
                phone: 555-555-0199
                company: Company
                country_name: United States
                country_code: US
                state_text: NY
                state_code: NY
                quick_checkout: false
                is_default_billing: false
                is_default_shipping: false
                state_abbr: NY
                country_iso: US
                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
                label:
                first_name: John
                last_name: Doe
                full_name: John Doe
                address1: 238 Lovely Street
                address2: Northwest
                postal_code: '10118'
                city: Los Angeles
                phone: 555-555-0199
                company: Company
                country_name: United States
                country_code: US
                state_text: NY
                state_code: NY
                quick_checkout: false
                is_default_billing: false
                is_default_shipping: false
                state_abbr: NY
                country_iso: US
                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 the authenticated customer's saved credit cards for the
        current store's payment methods
      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: mkt_UkLWZg9DAJ
                  withdrawal_period_ends_at:
                  within_withdrawal_period: true
                  cart_id:
                  channel_id: ch_UkLWZg9DAJ
                  company_id:
                  company_name:
                  po_document_filename:
                  po_document_byte_size:
                  number: R1001
                  email: idella.ratke@runolfsdottir.us
                  customer_note:
                  po_number:
                  currency: USD
                  locale: en
                  total_quantity: 1
                  coupon_code:
                  fulfillment_status:
                  payment_status:
                  completed_at: '2026-01-15T12:00:00.000Z'
                  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"
                  fee_total: '0.0'
                  display_fee_total: "$0.00"
                  store_credit_total: '0.0'
                  display_store_credit_total: "$0.00"
                  covered_by_store_credit: false
                  discounts: []
                  fees: []
                  items:
                  - id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    seller_id:
                    preorder: false
                    preorder_ships_at:
                    quantity: 1
                    currency: USD
                    name: Product 2535270
                    slug: product-2535270
                    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: R1001-F1
                    tracking: U10000
                    tracking_url:
                    pickup_point_data:
                    selected_delivery_rate_id: dr_gbHJdmfrXB
                    unpriced: false
                    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: unfulfilled
                    fulfillment_type: shipping
                    fulfilled_at:
                    delivered_at:
                    items:
                    - item_id: li_UkLWZg9DAJ
                      variant_id: variant_UkLWZg9DAJ
                      quantity: 1
                    deliveries:
                    - id: dlv_UkLWZg9DAJ
                      tracking_number: U10000
                      carrier:
                      carrier_name:
                      service:
                      status: pending
                      tracking_url:
                      estimated_delivery_at:
                      delivered_at:
                    delivery_method:
                      id: dm_UkLWZg9DAJ
                      name: UPS Ground 123
                      code: UPS_GROUND_140
                      estimated_transit_business_days_min:
                      estimated_transit_business_days_max:
                      digital: false
                      pickup: false
                      pickup_point: false
                    stock_location:
                      id: sloc_UkLWZg9DAJ
                      name: Macy Goyette
                      address1: 1600 Pennsylvania Ave NW
                      city: Washington
                      zipcode: '20500'
                      country_code: US
                      country_name: United States
                      state_code: AL
                      state_text: AL
                      pickup_ready_in_minutes:
                      pickup_instructions:
                    delivery_rates:
                    - id: dr_gbHJdmfrXB
                      delivery_method_id: dm_UkLWZg9DAJ
                      name: UPS Ground 123
                      selected: true
                      cost: '10.0'
                      total: '10.0'
                      additional_tax_total: '0.0'
                      included_tax_total: '0.0'
                      tax_total: '0.0'
                      carrier:
                      service_level:
                      estimated_delivery_date:
                      unpriced: false
                      freight_summary:
                      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 123
                        code: UPS_GROUND_140
                        estimated_transit_business_days_min:
                        estimated_transit_business_days_max:
                        digital: false
                        pickup: false
                        pickup_point: false
                  payments: []
                  billing_address:
                    id: addr_EfhxLZ9ck8
                    label:
                    first_name: John
                    last_name: Doe
                    full_name: John Doe
                    address1: 304 Lovely Street
                    address2: Northwest
                    postal_code: '10118'
                    city: New York
                    phone: 555-555-0199
                    company: Company
                    country_name: United States
                    country_code: US
                    state_text: NY
                    state_code: NY
                    quick_checkout: false
                    is_default_billing: false
                    is_default_shipping: false
                    state_abbr: NY
                    country_iso: US
                    state_name: New York
                  shipping_address:
                    id: addr_VqXmZF31wY
                    label:
                    first_name: John
                    last_name: Doe
                    full_name: John Doe
                    address1: 305 Lovely Street
                    address2: Northwest
                    postal_code: '10118'
                    city: New York
                    phone: 555-555-0199
                    company: Company
                    country_name: United States
                    country_code: US
                    state_text: NY
                    state_code: NY
                    quick_checkout: false
                    is_default_billing: false
                    is_default_shipping: false
                    state_abbr: NY
                    country_iso: US
                    state_name: New York
                  gift_card:
                  market:
                    id: mkt_UkLWZg9DAJ
                    name: United States
                    currency: USD
                    default_locale: en
                    tax_inclusive: false
                    default: true
                    country_codes:
                    - US
                    supported_locales:
                    - en
                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: mkt_UkLWZg9DAJ
                withdrawal_period_ends_at:
                within_withdrawal_period: true
                cart_id:
                channel_id: ch_UkLWZg9DAJ
                company_id:
                company_name:
                po_document_filename:
                po_document_byte_size:
                number: R1001
                email: whitney_homenick@leschwhite.co.uk
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                coupon_code:
                fulfillment_status:
                payment_status:
                completed_at: '2026-01-15T12:00:00.000Z'
                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"
                fee_total: '0.0'
                display_fee_total: "$0.00"
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                discounts: []
                fees: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  seller_id:
                  preorder: false
                  preorder_ships_at:
                  quantity: 1
                  currency: USD
                  name: Product 2555633
                  slug: product-2555633
                  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: R1001-F1
                  tracking: U10000
                  tracking_url:
                  pickup_point_data:
                  selected_delivery_rate_id: dr_gbHJdmfrXB
                  unpriced: false
                  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: unfulfilled
                  fulfillment_type: shipping
                  fulfilled_at:
                  delivered_at:
                  items:
                  - item_id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                  deliveries:
                  - id: dlv_UkLWZg9DAJ
                    tracking_number: U10000
                    carrier:
                    carrier_name:
                    service:
                    status: pending
                    tracking_url:
                    estimated_delivery_at:
                    delivered_at:
                  delivery_method:
                    id: dm_UkLWZg9DAJ
                    name: UPS Ground 125
                    code: UPS_GROUND_142
                    estimated_transit_business_days_min:
                    estimated_transit_business_days_max:
                    digital: false
                    pickup: false
                    pickup_point: false
                  stock_location:
                    id: sloc_UkLWZg9DAJ
                    name: Sunny Bernier
                    address1: 1600 Pennsylvania Ave NW
                    city: Washington
                    zipcode: '20500'
                    country_code: US
                    country_name: United States
                    state_code: AL
                    state_text: AL
                    pickup_ready_in_minutes:
                    pickup_instructions:
                  delivery_rates:
                  - id: dr_gbHJdmfrXB
                    delivery_method_id: dm_UkLWZg9DAJ
                    name: UPS Ground 125
                    selected: true
                    cost: '10.0'
                    total: '10.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    carrier:
                    service_level:
                    estimated_delivery_date:
                    unpriced: false
                    freight_summary:
                    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 125
                      code: UPS_GROUND_142
                      estimated_transit_business_days_min:
                      estimated_transit_business_days_max:
                      digital: false
                      pickup: false
                      pickup_point: false
                payments: []
                billing_address:
                  id: addr_EfhxLZ9ck8
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 310 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_abbr: NY
                  country_iso: US
                  state_name: New York
                shipping_address:
                  id: addr_VqXmZF31wY
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 311 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_abbr: NY
                  country_iso: US
                  state_name: New York
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
              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.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjY0OWM2NTkzLTBhZWQtNDA5Ny1hYTI3LThhMjVmYTU4OGI3OSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.llCt1j8kVryteixNYywlzA1x8CGqCNBaKiT3-ihDrsE
                refresh_token: mLm6vdSzLUgPhw8SCzDiagfL
                user:
                  id: cust_UkLWZg9DAJ
                  email: newuser@example.com
                  first_name: John
                  last_name: Doe
                  phone: "+1234567890"
                  accepts_email_marketing: true
                  email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
                  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-01-15T12:00:00.000Z'
                    updated_at: '2026-01-15T12:00:00.000Z'
                    verified: true
                    verified_at: '2026-01-15T12:00:00Z'
                    customer_id: cust_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: cust_UkLWZg9DAJ
                email: rochell@schoen.name
                first_name: Felix
                last_name: Rowe
                phone: 555-555-0199
                accepts_email_marketing: false
                email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
                full_name: Felix Rowe
                available_store_credit_total: '0'
                display_available_store_credit_total: "$0.00"
                addresses:
                - id: addr_UkLWZg9DAJ
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 316 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: true
                  state_abbr: NY
                  country_iso: US
                  state_name: New York
                - id: addr_gbHJdmfrXB
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 317 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: true
                  is_default_shipping: false
                  state_abbr: NY
                  country_iso: US
                  state_name: New York
                default_billing_address:
                  id: addr_gbHJdmfrXB
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 317 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: true
                  is_default_shipping: false
                  state_abbr: NY
                  country_iso: US
                  state_name: New York
                default_shipping_address:
                  id: addr_UkLWZg9DAJ
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 316 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: true
                  state_abbr: NY
                  country_iso: US
                  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: cust_UkLWZg9DAJ
                email: tabitha@ziemebogisich.info
                first_name: Updated
                last_name: Name
                phone: 555-555-0199
                accepts_email_marketing: false
                email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
                full_name: Updated Name
                available_store_credit_total: '0'
                display_available_store_credit_total: "$0.00"
                addresses:
                - id: addr_UkLWZg9DAJ
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 318 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: true
                  state_abbr: NY
                  country_iso: US
                  state_name: New York
                - id: addr_gbHJdmfrXB
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 319 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: true
                  is_default_shipping: false
                  state_abbr: NY
                  country_iso: US
                  state_name: New York
                default_billing_address:
                  id: addr_gbHJdmfrXB
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 319 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: true
                  is_default_shipping: false
                  state_abbr: NY
                  country_iso: US
                  state_name: New York
                default_shipping_address:
                  id: addr_UkLWZg9DAJ
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 318 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: true
                  state_abbr: NY
                  country_iso: US
                  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/data_requests":
    get:
      summary: List data requests
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Returns the authenticated customer's GDPR data requests, most recent
        first
      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
      responses:
        '200':
          description: data requests found
          content:
            application/json:
              example:
                data:
                - id: dsr_UkLWZg9DAJ
                  number: DSR1001
                  kind: access
                  status: pending
                  requested_at: '2026-01-15T12:00:00Z'
                  completed_at:
                  expires_at:
                  download_url:
                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/DataRequest"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
    post:
      summary: Open a data request
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |
        Opens a GDPR request for a copy of the customer's personal data (`access`)
        or its erasure (`erasure`). The work happens in the background and the
        response is the pending request.

        An erasure request requires the account password. A request of the same
        kind that is still in flight is returned instead of starting a second one.
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '202':
          description: request accepted
          content:
            application/json:
              example:
                id: dsr_UkLWZg9DAJ
                number: DSR1001
                kind: access
                status: pending
                requested_at: '2026-01-15T12:00:00Z'
                completed_at:
                expires_at:
                download_url:
              schema:
                "$ref": "#/components/schemas/DataRequest"
        '422':
          description: erasure without the account password
          content:
            application/json:
              example:
                error:
                  code: current_password_invalid
                  message: Current password is invalid or missing
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                kind:
                  type: string
                  enum:
                  - access
                  - erasure
                  description: Defaults to access
                current_password:
                  type: string
                  description: Required for erasure
  "/api/v3/store/customers/me/data_requests/{id}":
    get:
      summary: Get a data request
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Returns one of the customer's own data requests, with a download
        link once the export is ready
      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: data request found
          content:
            application/json:
              example:
                id: dsr_UkLWZg9DAJ
                number: DSR1001
                kind: access
                status: pending
                requested_at: '2026-01-15T12:00:00Z'
                completed_at:
                expires_at:
                download_url:
              schema:
                "$ref": "#/components/schemas/DataRequest"
        '404':
          description: not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Data request not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/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: 1A288BF2DA45E295
                  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: B7180B830F0E5992
                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_b0f840e3d99ea3a536ef5be0
                external_client_secret: bogus_seti_secret_8fa01173ccc21ceb
                external_data: {}
                payment_method_id: pm_UkLWZg9DAJ
                payment_source_id:
                payment_source_type:
                customer_id: cust_UkLWZg9DAJ
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Credit Card 127
                  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_469ea499603a54b5a5f4b192
                external_client_secret: seti_secret_ee50fe0dfcb78f21eabebb03
                external_data:
                  client_secret: secret_123
                payment_method_id: pm_UkLWZg9DAJ
                payment_source_id:
                payment_source_type:
                customer_id: cust_UkLWZg9DAJ
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Credit Card 130
                  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_d9e0e43453e8ba9aff74d4b9
                external_client_secret: seti_secret_73ff06ddd3b1edb4c9b6db1c
                external_data:
                  client_secret: secret_123
                payment_method_id: pm_UkLWZg9DAJ
                payment_source_id: card_UkLWZg9DAJ
                payment_source_type: Spree::CreditCard
                customer_id: cust_UkLWZg9DAJ
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Credit Card 132
                  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: DEU
                  name: Germany
                  states_required: false
                  zipcode_required: true
                - iso: US
                  iso3: USA
                  name: United States
                  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
                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: record 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: "€"
                - iso_code: GBP
                  name: British Pound
                  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_codes:
                  - US
                  supported_locales:
                  - en
                  - es
                  countries:
                  - iso: US
                    iso3: USA
                    name: United States
                    states_required: true
                    zipcode_required: true
                - id: mkt_gbHJdmfrXB
                  name: Europe
                  currency: EUR
                  default_locale: de
                  tax_inclusive: true
                  default: false
                  country_codes:
                  - DE
                  - FR
                  supported_locales:
                  - de
                  - en
                  - fr
                  countries:
                  - iso: FR
                    iso3: FRA
                    name: France
                    states_required: false
                    zipcode_required: true
                  - iso: DE
                    iso3: DEU
                    name: Germany
                    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_codes:
                - DE
                - FR
                supported_locales:
                - de
                - en
                - fr
                countries:
                - iso: FR
                  iso3: FRA
                  name: France
                  states_required: false
                  zipcode_required: true
                - iso: DE
                  iso3: DEU
                  name: Germany
                  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_codes:
                - DE
                - FR
                supported_locales:
                - de
                - en
                - fr
                countries:
                - iso: FR
                  iso3: FRA
                  name: France
                  states_required: false
                  zipcode_required: true
                - iso: DE
                  iso3: DEU
                  name: Germany
                  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: record 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: FRA
                  name: France
                  states_required: false
                  zipcode_required: true
                - iso: DE
                  iso3: DEU
                  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
                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: record 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: Po2FxovL4CYgapsDQCvBKmwP
                  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: 9QwEwKPqhv9b6g6vN3mSu4Pm
                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: MScw7Kpbgn8BpAxVkttfKab8
                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: AMc2ph626mbJo7u5VjvVs9CA
                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-436
                  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:
                  weight_unit: lb
                  dimensions_unit: in
                  minimum_order_quantity: 1
                  order_multiple: 1
                  purchase_unit: unit
                  units_per_carton:
                  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:
                  seller_id:
                  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: Wishlist 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: phung.sawayn@carterfunk.ca
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                verified: true
                verified_at: '2026-01-15T12:00:00Z'
                customer_id: cust_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-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                verified: true
                verified_at: '2026-01-15T12:00:00Z'
                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: ''
                  updated_at: '2026-01-15T12:00:00.000Z'
                - id: pol_OIJLhNcSbf
                  name: Privacy Policy
                  slug: privacy-policy-f4e5666d-52c2-4d89-aec5-cc55d69c7174
                  body: We respect your privacy.
                  body_html: We respect your privacy.
                  updated_at: '2026-01-15T12:00:00.000Z'
                - id: pol_uw2YK1rnl0
                  name: Return Policy
                  slug: return-policy
                  body: You can return items within 30 days.
                  body_html: You can return items within 30 days.
                  updated_at: '2026-01-15T12:00:00.000Z'
                - id: pol_EfhxLZ9ck8
                  name: Returns Policy
                  slug: returns-policy
                  body: ''
                  body_html: ''
                  updated_at: '2026-01-15T12:00:00.000Z'
                - id: pol_VqXmZF31wY
                  name: Shipping Policy
                  slug: shipping-policy
                  body: ''
                  body_html: ''
                  updated_at: '2026-01-15T12:00:00.000Z'
                - id: pol_UkLWZg9DAJ
                  name: Terms of Service
                  slug: terms-of-service
                  body: ''
                  body_html: ''
                  updated_at: '2026-01-15T12:00:00.000Z'
                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: You can return items within 30 days.
                updated_at: '2026-01-15T12:00:00.000Z'
              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/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"
  "/api/v3/store/account/companies":
    get:
      summary: List my company memberships
      tags:
      - Companies
      security:
      - api_key: []
        bearer_auth: []
      description: |
        Returns the authenticated customer's company memberships, each with the node it
        is held on and the path of nodes above it. Standing covers the node and every
        node below it, so a membership on a parent authorizes buying for its divisions.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

          // The buyer's memberships, each carrying its node and the path above it.
          const { data: memberships } = await client.account.companies({ 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: memberships listed
          content:
            application/json:
              example:
                data:
                - id: cmem_UkLWZg9DAJ
                  company_id: comp_UkLWZg9DAJ
                  customer_id: cust_UkLWZg9DAJ
                  email: pasty.koepp@farrell.name
                  company:
                    id: comp_UkLWZg9DAJ
                    name: Acme Industrial
                    kind: company
                    po_number_required: false
                    parent_id:
                    ancestors: []
        '401':
          description: not authenticated
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
  "/api/v3/store/companies/{id}":
    parameters:
    - name: id
      in: path
      required: true
      description: Company node ID (comp_...)
      schema:
        type: string
    get:
      summary: Get a company node
      tags:
      - Companies
      security:
      - api_key: []
        bearer_auth: []
      description: |
        Returns one node of the buyer's organization. Requires standing — a membership on
        the node or on one of its ancestors; any other node is not found rather than
        refused, so its existence is not disclosed.
      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 company = await client.companies.get('comp_86Rf07xd4z', { 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: company found
          content:
            application/json:
              example:
                id: comp_UkLWZg9DAJ
                name: Acme Industrial
                kind: company
                po_number_required: false
                parent_id:
                ancestors: []
        '404':
          description: no standing over this node
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Company not found
    patch:
      summary: Update a company node
      tags:
      - Companies
      security:
      - api_key: []
        bearer_auth: []
      description: Renames the node. Structure — the parent and the kind — is managed
        by the merchant, not by buyers.
      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: company updated
          content:
            application/json:
              example:
                id: comp_UkLWZg9DAJ
                name: Acme Industrial Group
                kind: company
                po_number_required: false
                parent_id:
                ancestors: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Acme Industrial Group
  "/api/v3/store/companies/{company_id}/members":
    parameters:
    - name: company_id
      in: path
      required: true
      description: Company node ID (comp_...)
      schema:
        type: string
    get:
      summary: List company members
      tags:
      - Companies
      security:
      - api_key: []
        bearer_auth: []
      description: The people with standing over this node. Within a company every
        member may read and manage the directory.
      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: members listed
          content:
            application/json:
              example:
                data:
                - id: cmem_UkLWZg9DAJ
                  company_id: comp_UkLWZg9DAJ
                  customer_id: cust_UkLWZg9DAJ
                  email: su_kuvalis@ward.biz
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
    post:
      summary: Add a member by email
      tags:
      - Companies
      security:
      - api_key: []
        bearer_auth: []
      description: |
        Adds a person to the node by email. An email that already belongs to a customer of
        this store becomes a membership immediately (a `cmem_...` id); any other email
        becomes an invitation (a `cinv_...` id) and the invite email goes 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>',
          })

          // An existing customer joins immediately (cmem_…); anyone else is emailed an
          // invitation (cinv_…).
          const member = await client.companies.members.create(
            'comp_86Rf07xd4z',
            { customer_email: 'colleague@acme.test' },
            { 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: member added or invitation sent
          content:
            application/json:
              example:
                id: cmem_gbHJdmfrXB
                company_id: comp_UkLWZg9DAJ
                customer_id: cust_gbHJdmfrXB
                email: colleague@acme.test
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_email:
                  type: string
                  example: colleague@acme.test
              required:
              - customer_email
  "/api/v3/store/companies/{company_id}/addresses":
    parameters:
    - name: company_id
      in: path
      required: true
      description: Company node ID (comp_...)
      schema:
        type: string
    get:
      summary: List the company address book
      tags:
      - Companies
      security:
      - api_key: []
        bearer_auth: []
      description: The labeled ship-to and bill-to sites this node owns. A node with
        no default of its own falls back to its nearest ancestor when prefilling checkout.
      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: addresses listed
          content:
            application/json:
              example:
                data:
                - id: addr_EfhxLZ9ck8
                  label: Headquarters
                  first_name:
                  last_name:
                  full_name: ''
                  address1: 277 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_abbr: NY
                  country_iso: US
                  state_name: New York
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
  "/api/v3/store/companies/{company_id}/addresses/{id}":
    parameters:
    - name: company_id
      in: path
      required: true
      description: Company node ID (comp_...)
      schema:
        type: string
    - name: id
      in: path
      required: true
      description: Address ID (addr_...)
      schema:
        type: string
    patch:
      summary: Update an address book entry
      tags:
      - Companies
      security:
      - api_key: []
        bearer_auth: []
      description: Renames a site or moves the default ship-to or bill-to flag to
        it. Only one entry per node holds each default.
      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: address book entry updated
          content:
            application/json:
              example:
                id: addr_EfhxLZ9ck8
                label: Northern Warehouse
                first_name:
                last_name:
                full_name: ''
                address1: 280 Lovely Street
                address2: Northwest
                postal_code: '10118'
                city: New York
                phone: 555-555-0199
                company: Company
                country_name: United States
                country_code: US
                state_text: NY
                state_code: NY
                quick_checkout: false
                is_default_billing: false
                is_default_shipping: true
                state_abbr: NY
                country_iso: US
                state_name: New York
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  type: string
                  example: Northern Warehouse
                default_shipping:
                  type: boolean
                  example: true
    delete:
      summary: Remove an address book entry
      tags:
      - Companies
      security:
      - api_key: []
        bearer_auth: []
      description: Takes the site out of the address book. Orders already placed to
        it keep their own copy of the address.
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '204':
          description: address book entry removed
  "/api/v3/store/companies/{company_id}/invitations/{id}":
    parameters:
    - name: company_id
      in: path
      required: true
      description: Company node ID (comp_...)
      schema:
        type: string
    - name: id
      in: path
      required: true
      description: Invitation ID (cinv_...)
      schema:
        type: string
    delete:
      summary: Revoke an invitation
      tags:
      - Companies
      security:
      - api_key: []
        bearer_auth: []
      description: Withdraws a pending invitation, spending its token. Any member
        with standing over the node may revoke.
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '204':
          description: invitation revoked
  "/api/v3/store/companies/{company_id}/orders":
    parameters:
    - name: company_id
      in: path
      required: true
      description: Company node ID (comp_...)
      schema:
        type: string
    get:
      summary: List the company purchases
      tags:
      - Companies
      security:
      - api_key: []
        bearer_auth: []
      description: Completed orders placed for this node and every node below it,
        so a parent sees what its divisions bought.
      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: orders listed
          content:
            application/json:
              example:
                data:
                - id: or_UkLWZg9DAJ
                  market_id: mkt_UkLWZg9DAJ
                  withdrawal_period_ends_at:
                  within_withdrawal_period: true
                  cart_id:
                  channel_id: ch_UkLWZg9DAJ
                  company_id: comp_UkLWZg9DAJ
                  company_name: Acme Industrial
                  po_document_filename:
                  po_document_byte_size:
                  number: R1001
                  email: chanell_langosh@schamberger.info
                  customer_note:
                  po_number:
                  currency: USD
                  locale: en
                  total_quantity: 1
                  coupon_code:
                  fulfillment_status:
                  payment_status:
                  completed_at: '2026-01-15T12:00:00.000Z'
                  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"
                  fee_total: '0.0'
                  display_fee_total: "$0.00"
                  store_credit_total: '0.0'
                  display_store_credit_total: "$0.00"
                  covered_by_store_credit: false
                  discounts: []
                  fees: []
                  items:
                  - id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    seller_id:
                    preorder: false
                    preorder_ships_at:
                    quantity: 1
                    currency: USD
                    name: Product 2525649
                    slug: product-2525649
                    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: R1001-F1
                    tracking: U10000
                    tracking_url:
                    pickup_point_data:
                    selected_delivery_rate_id: dr_gbHJdmfrXB
                    unpriced: false
                    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: unfulfilled
                    fulfillment_type: shipping
                    fulfilled_at:
                    delivered_at:
                    items:
                    - item_id: li_UkLWZg9DAJ
                      variant_id: variant_UkLWZg9DAJ
                      quantity: 1
                    deliveries:
                    - id: dlv_UkLWZg9DAJ
                      tracking_number: U10000
                      carrier:
                      carrier_name:
                      service:
                      status: pending
                      tracking_url:
                      estimated_delivery_at:
                      delivered_at:
                    delivery_method:
                      id: dm_UkLWZg9DAJ
                      name: UPS Ground 114
                      code: UPS_GROUND_131
                      estimated_transit_business_days_min:
                      estimated_transit_business_days_max:
                      digital: false
                      pickup: false
                      pickup_point: false
                    stock_location:
                      id: sloc_UkLWZg9DAJ
                      name: Kali Pacocha
                      address1: 1600 Pennsylvania Ave NW
                      city: Washington
                      zipcode: '20500'
                      country_code: US
                      country_name: United States
                      state_code: AL
                      state_text: AL
                      pickup_ready_in_minutes:
                      pickup_instructions:
                    delivery_rates:
                    - id: dr_gbHJdmfrXB
                      delivery_method_id: dm_UkLWZg9DAJ
                      name: UPS Ground 114
                      selected: true
                      cost: '10.0'
                      total: '10.0'
                      additional_tax_total: '0.0'
                      included_tax_total: '0.0'
                      tax_total: '0.0'
                      carrier:
                      service_level:
                      estimated_delivery_date:
                      unpriced: false
                      freight_summary:
                      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 114
                        code: UPS_GROUND_131
                        estimated_transit_business_days_min:
                        estimated_transit_business_days_max:
                        digital: false
                        pickup: false
                        pickup_point: false
                  payments: []
                  billing_address:
                    id: addr_EfhxLZ9ck8
                    label:
                    first_name: John
                    last_name: Doe
                    full_name: John Doe
                    address1: 288 Lovely Street
                    address2: Northwest
                    postal_code: '10118'
                    city: New York
                    phone: 555-555-0199
                    company: Company
                    country_name: United States
                    country_code: US
                    state_text: NY
                    state_code: NY
                    quick_checkout: false
                    is_default_billing: false
                    is_default_shipping: false
                    state_abbr: NY
                    country_iso: US
                    state_name: New York
                  shipping_address:
                    id: addr_VqXmZF31wY
                    label:
                    first_name: John
                    last_name: Doe
                    full_name: John Doe
                    address1: 289 Lovely Street
                    address2: Northwest
                    postal_code: '10118'
                    city: New York
                    phone: 555-555-0199
                    company: Company
                    country_name: United States
                    country_code: US
                    state_text: NY
                    state_code: NY
                    quick_checkout: false
                    is_default_billing: false
                    is_default_shipping: false
                    state_abbr: NY
                    country_iso: US
                    state_name: New York
                  gift_card:
                  market:
                    id: mkt_UkLWZg9DAJ
                    name: United States
                    currency: USD
                    default_locale: en
                    tax_inclusive: false
                    default: true
                    country_codes:
                    - US
                    supported_locales:
                    - en
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
  "/api/v3/store/company_invitations/{token}":
    parameters:
    - name: token
      in: path
      required: true
      description: Plaintext invitation token from the invite email
      schema:
        type: string
    get:
      summary: Look up an invitation
      tags:
      - Companies
      security:
      - api_key: []
      description: |
        Shows what is being joined, so the acceptance page can render before the invitee
        has an account. Deliberately unauthenticated — the token from the email is the
        credential. Spent, revoked and expired tokens are not found.
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: invitation found
          content:
            application/json:
              example:
                id: cinv_UkLWZg9DAJ
                email: new@acme.test
                expires_at: '2026-02-14T12:00:00.000Z'
                company_id: comp_UkLWZg9DAJ
                status: pending
                company_name: Acme Industrial
                store_name: Spree Test Store
        '404':
          description: token spent, revoked or expired
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Company invitation not found
  "/api/v3/store/company_invitations/{token}/accept":
    parameters:
    - name: token
      in: path
      required: true
      description: Plaintext invitation token from the invite email
      schema:
        type: string
    post:
      summary: Accept an invitation
      tags:
      - Companies
      security:
      - api_key: []
      description: |
        Turns the invitation into a membership. Send a registration payload to create the
        account — it is always created with the invited email — or call it authenticated as
        the customer who owns that email to bind the invitation to the existing 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>',
          })

          // Unauthenticated: the token from the invite email is the credential, and the
          // registration payload creates the account with the invited address.
          const membership = await client.companyInvitations.accept('<invitation-token>', {
            first_name: 'Ada',
            password: 'a-strong-password',
            password_confirmation: 'a-strong-password',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '201':
          description: membership created
          content:
            application/json:
              example:
                id: cmem_UkLWZg9DAJ
                company_id: comp_UkLWZg9DAJ
                customer_id: cust_UkLWZg9DAJ
                email: new@acme.test
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                  example: Ada
                last_name:
                  type: string
                  example: Lovelace
                password:
                  type: string
                  example: a-strong-password
                password_confirmation:
                  type: string
                  example: a-strong-password
  "/api/v3/store/delivery_methods":
    get:
      summary: List delivery methods
      tags:
      - Delivery
      security:
      - api_key: []
      description: Storefront-visible delivery methods. Filter by fulfillment_type
        to discover pickup options.
      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 { data: pickupMethods } = await client.deliveryMethods.list({
            fulfillment_type: 'pickup',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: fulfillment_type
        in: query
        required: false
        description: 'Filter: shipping, digital, pickup'
        schema:
          type: string
      responses:
        '200':
          description: delivery methods found
          content:
            application/json:
              example:
                data:
                - id: dm_gbHJdmfrXB
                  name: Store pickup
                  code: PICKUP_1
                  estimated_transit_business_days_min:
                  estimated_transit_business_days_max:
                  digital: false
                  pickup: true
                  pickup_point: false
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
  "/api/v3/store/delivery_methods/{id}/pickup_locations":
    get:
      summary: List pickup locations
      tags:
      - Delivery
      security:
      - api_key: []
      description: Pickup-enabled stock locations for a pickup delivery method. Pass
        cart_id to keep only locations that can fulfill the whole cart from local
        stock.
      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 { data: pickupLocations } = await client.deliveryMethods.pickupLocations('dm_abc123', {
            cart_id: 'cart_abc123',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Delivery method prefixed ID
        schema:
          type: string
      - name: cart_id
        in: query
        required: false
        description: Cart prefixed ID for availability filtering
        schema:
          type: string
      responses:
        '200':
          description: pickup locations found
          content:
            application/json:
              example:
                data:
                - id: sloc_UkLWZg9DAJ
                  name: Downtown
                  address1: 1600 Pennsylvania Ave NW
                  city: Washington
                  zipcode: '20500'
                  country_code: US
                  country_name: United States
                  state_code: AL
                  state_text: AL
                  pickup_ready_in_minutes:
                  pickup_instructions:
  "/api/v3/store/digital_links/{token}":
    get:
      summary: Download a digital product
      tags:
      - Digital Links
      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.

        Responds with a redirect to a short-lived download URL; follow it to
        fetch the file. Each download increments the access counter. Downloads
        may be limited by the asset's own settings, falling back to the store's
        (number of downloads and/or time-based expiration).
      parameters:
      - name: token
        in: path
        required: true
        description: Digital link token
        schema:
          type: string
      responses:
        '302':
          description: redirect to the file download
        '403':
          description: download link expired or limit exceeded
          content:
            application/json:
              example:
                error:
                  code: digital_link_expired
                  message: Download link expired or invalid
              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
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/sellers":
    get:
      summary: List sellers
      tags:
      - Sellers
      security:
      - api_key: []
      description: |
        Returns the sellers on this marketplace that a shopper can currently
        buy from. A seller still onboarding, suspended, or away on holiday is
        not listed — showing them would advertise a seller whose products
        cannot be bought.

        The payload is the seller's public profile only. Nothing about how the
        marketplace runs them — status, payout schedule, tax handling, contact
        addresses — is exposed here.
      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: expand
        in: query
        required: false
        description: Comma-separated associations to expand (`policies`). A seller's
          policies are their own published legal documents.
        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: sellers found
          content:
            application/json:
              example:
                data:
                - id: sel_UkLWZg9DAJ
                  name: Sparks Audio
                  slug: sparks-audio
                  about: ''
                  about_html: ''
                  logo_url:
                  square_logo_url:
                  cover_photo_url:
                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/Seller"
                  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/sellers/{id}":
    get:
      summary: Get a seller
      tags:
      - Sellers
      security:
      - api_key: []
      description: |
        Returns a single seller's public profile, by slug or prefixed ID, so a
        storefront can route `/sellers/sparks-audio` without holding an id.

        A seller who cannot currently sell returns 404 rather than a profile.
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Seller slug (e.g., sparks-audio) or prefixed ID (e.g., sel_abc123)
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (`policies`). A seller's
          policies are their own published legal documents.
        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: seller found by slug
          content:
            application/json:
              example:
                id: sel_UkLWZg9DAJ
                name: Sparks Audio
                slug: sparks-audio
                about: ''
                about_html: ''
                logo_url:
                square_logo_url:
                cover_photo_url:
              schema:
                "$ref": "#/components/schemas/Seller"
        '404':
          description: seller not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Seller not found
              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
    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
        item_index:
          type: integer
          nullable: true
          description: Position in the submitted items array, for warnings raised
            while applying a batch of item changes
          example: 1
      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
        label:
          type: string
          nullable: true
        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_code:
          type: string
        state_text:
          type: string
          nullable: true
        state_code:
          type: string
          nullable: true
        quick_checkout:
          type: boolean
        is_default_billing:
          type: boolean
        is_default_shipping:
          type: boolean
        state_abbr:
          type: string
          nullable: true
        country_iso:
          type: string
        state_name:
          type: string
          nullable: true
      required:
      - id
      - label
      - first_name
      - last_name
      - full_name
      - address1
      - address2
      - postal_code
      - city
      - phone
      - company
      - country_name
      - country_code
      - state_text
      - state_code
      - quick_checkout
      - is_default_billing
      - is_default_shipping
      - state_abbr
      - country_iso
      - state_name
      x-typelizer: true
    AppliedPromotion:
      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
    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
        preferred_stock_location_id:
          type: string
          nullable: true
        company_id:
          type: string
          nullable: true
        company_name:
          type: string
          nullable: true
        po_number_required:
          type: boolean
        po_document_filename:
          type: string
          nullable: true
        po_document_byte_size:
          type: number
          nullable: true
        number:
          type: string
        token:
          type: string
        email:
          type: string
          nullable: true
        customer_note:
          type: string
          nullable: true
        po_number:
          type: string
          nullable: true
        currency:
          type: string
        locale:
          type: string
          nullable: true
        total_quantity:
          type: number
        warnings:
          type: array
          items:
            "$ref": "#/components/schemas/CartWarning"
        coupon_code:
          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
        fee_total:
          type: string
          nullable: true
        display_fee_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"
        order_minimum:
          type: number
          nullable: true
        order_minimum_shortfall:
          type: number
          nullable: true
        below_order_minimum:
          type: boolean
          nullable: true
        freight_summary:
          allOf:
          - "$ref": "#/components/schemas/FreightSummary"
          nullable: true
        shipping_eq_billing_address:
          type: boolean
        discounts:
          type: array
          items:
            "$ref": "#/components/schemas/AppliedPromotion"
        fees:
          type: array
          items:
            "$ref": "#/components/schemas/Fee"
        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
      - preferred_stock_location_id
      - company_id
      - company_name
      - po_number_required
      - po_document_filename
      - po_document_byte_size
      - number
      - token
      - email
      - customer_note
      - po_number
      - currency
      - locale
      - total_quantity
      - warnings
      - coupon_code
      - 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
      - fee_total
      - display_fee_total
      - store_credit_total
      - display_store_credit_total
      - covered_by_store_credit
      - current_step
      - completed_steps
      - requirements
      - order_minimum
      - order_minimum_shortfall
      - below_order_minimum
      - freight_summary
      - shipping_eq_billing_address
      - discounts
      - fees
      - 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
    ClaimLineItem:
      type: object
      properties:
        id:
          type: string
        quantity:
          type: number
        send_replacement:
          type: boolean
        description:
          type: string
          nullable: true
        refund_amount:
          type: string
        paid_amount:
          type: string
        display_refund_amount:
          type: string
        variant_id:
          type: string
          nullable: true
        replacement_variant_id:
          type: string
          nullable: true
        line_item_id:
          type: string
          nullable: true
        variant:
          "$ref": "#/components/schemas/Variant"
      required:
      - id
      - quantity
      - send_replacement
      - description
      - refund_amount
      - paid_amount
      - display_refund_amount
      - variant_id
      - replacement_variant_id
      - line_item_id
      x-typelizer: true
    ClaimReason:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        active:
          type: boolean
      required:
      - id
      - name
      - active
      x-typelizer: true
    Claim:
      type: object
      properties:
        id:
          type: string
        number:
          type: string
        status:
          anyOf:
          - type: string
            enum:
            - open
            - approved
            - resolved
            - denied
            - canceled
          - type: string
          description: The values listed are the built-in ones; extensions may add
            more.
        resolution:
          type: string
          nullable: true
        order_id:
          type: string
          nullable: true
        reason_id:
          type: string
          nullable: true
        refund_total:
          type: string
        display_refund_total:
          type: string
        approved_at:
          type: string
          nullable: true
        resolved_at:
          type: string
          nullable: true
        denied_at:
          type: string
          nullable: true
        canceled_at:
          type: string
          nullable: true
        reason:
          "$ref": "#/components/schemas/ClaimReason"
        claim_line_items:
          type: array
          items:
            "$ref": "#/components/schemas/ClaimLineItem"
      required:
      - id
      - number
      - status
      - resolution
      - order_id
      - reason_id
      - refund_total
      - display_refund_total
      - approved_at
      - resolved_at
      - denied_at
      - canceled_at
      x-typelizer: true
    Collection:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        permalink:
          type: string
        position:
          type: number
        sort_order:
          type: string
        meta_title:
          type: string
          nullable: true
        meta_description:
          type: string
          nullable: true
        meta_keywords:
          type: string
          nullable: true
        products_count:
          type: number
        description:
          type: string
        description_html:
          type: string
        image_url:
          type: string
          nullable: true
        square_image_url:
          type: string
          nullable: true
        custom_fields:
          type: array
          items:
            "$ref": "#/components/schemas/CustomField"
      required:
      - id
      - name
      - permalink
      - position
      - sort_order
      - meta_title
      - meta_description
      - meta_keywords
      - products_count
      - description
      - description_html
      - image_url
      - square_image_url
      x-typelizer: true
    CompanyInvitation:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        expires_at:
          type: string
          nullable: true
        company_id:
          type: string
        status:
          type: string
          enum:
          - pending
          - accepted
          - revoked
          - expired
      required:
      - id
      - email
      - expires_at
      - company_id
      - status
      x-typelizer: true
    CompanyMembership:
      type: object
      properties:
        id:
          type: string
        company_id:
          type: string
        customer_id:
          type: string
        email:
          type: string
          nullable: true
      required:
      - id
      - company_id
      - customer_id
      - email
      x-typelizer: true
    Company:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        kind:
          type: string
          enum:
          - company
          - division
        po_number_required:
          type: boolean
        parent_id:
          type: string
          nullable: true
        ancestors:
          type: object
      required:
      - id
      - name
      - kind
      - po_number_required
      - parent_id
      - ancestors
      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
        email_marketing_consent_updated_at:
          type: string
          nullable: true
        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
      - email_marketing_consent_updated_at
      - 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
    DataRequestEvent:
      type: object
      properties:
        id:
          type: string
        number:
          type: string
        kind:
          type: string
          enum:
          - access
          - erasure
        status:
          anyOf:
          - type: string
            enum:
            - pending
            - processing
            - completed
            - failed
          - type: string
          description: The values listed are the built-in ones; extensions may add
            more.
        requested_at:
          type: string
          nullable: true
        completed_at:
          type: string
          nullable: true
      required:
      - id
      - number
      - kind
      - status
      - requested_at
      - completed_at
      x-typelizer: true
    DataRequest:
      type: object
      properties:
        id:
          type: string
        number:
          type: string
        kind:
          type: string
          enum:
          - access
          - erasure
        status:
          anyOf:
          - type: string
            enum:
            - pending
            - processing
            - completed
            - failed
          - type: string
          description: The values listed are the built-in ones; extensions may add
            more.
        requested_at:
          type: string
          nullable: true
        completed_at:
          type: string
          nullable: true
        expires_at:
          type: string
          nullable: true
        download_url:
          type: string
          nullable: true
      required:
      - id
      - number
      - kind
      - status
      - requested_at
      - completed_at
      - expires_at
      - download_url
      x-typelizer: true
    DeliveryMethod:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        code:
          type: string
          nullable: true
        estimated_transit_business_days_min:
          type: number
          nullable: true
        estimated_transit_business_days_max:
          type: number
          nullable: true
        digital:
          type: boolean
        pickup:
          type: boolean
        pickup_point:
          type: boolean
      required:
      - id
      - name
      - code
      - estimated_transit_business_days_min
      - estimated_transit_business_days_max
      - digital
      - pickup
      - pickup_point
      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
        carrier:
          type: string
          nullable: true
        service_level:
          type: string
          nullable: true
        estimated_delivery_date:
          type: string
          nullable: true
        unpriced:
          type: boolean
        freight_summary:
          allOf:
          - "$ref": "#/components/schemas/FreightSummary"
          nullable: true
        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
      - carrier
      - service_level
      - estimated_delivery_date
      - unpriced
      - freight_summary
      - display_cost
      - display_total
      - display_additional_tax_total
      - display_included_tax_total
      - display_tax_total
      - delivery_method
      x-typelizer: true
    Delivery:
      type: object
      properties:
        id:
          type: string
        tracking_number:
          type: string
        carrier:
          type: string
          nullable: true
        carrier_name:
          type: string
          nullable: true
        service:
          type: string
          nullable: true
        status:
          type: string
          enum:
          - pending
          - pre_transit
          - in_transit
          - out_for_delivery
          - available_for_pickup
          - delivered
          - return_to_sender
          - failure
          - unknown
        tracking_url:
          type: string
          nullable: true
        estimated_delivery_at:
          type: string
          nullable: true
        delivered_at:
          type: string
          nullable: true
      required:
      - id
      - tracking_number
      - carrier
      - carrier_name
      - service
      - status
      - tracking_url
      - estimated_delivery_at
      - delivered_at
      x-typelizer: true
    DeliveryZoneMember:
      type: object
      properties:
        id:
          type: string
        member_type:
          type: string
          enum:
          - country
          - state
          - postal_code
        country_code:
          type: string
          nullable: true
        state_code:
          type: string
          nullable: true
        postal_code_prefix:
          type: string
          nullable: true
        postal_code_from:
          type: string
          nullable: true
        postal_code_to:
          type: string
          nullable: true
        country_name:
          type: string
          nullable: true
        state_name:
          type: string
          nullable: true
      required:
      - id
      - member_type
      - country_code
      - state_code
      - postal_code_prefix
      - postal_code_from
      - postal_code_to
      - country_name
      - state_name
      x-typelizer: true
    DeliveryZone:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        members:
          type: array
          items:
            "$ref": "#/components/schemas/DeliveryZoneMember"
      required:
      - id
      - name
      - description
      x-typelizer: true
    DigitalAsset:
      type: object
      properties:
        id:
          type: string
        variant_id:
          type: string
          nullable: true
        filename:
          type: string
          nullable: true
        content_type:
          type: string
          nullable: true
      required:
      - id
      - variant_id
      - filename
      - content_type
      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
        expires_at:
          type: string
          nullable: true
        authorizable:
          type: boolean
        expired:
          type: boolean
        access_limit_exceeded:
          type: boolean
      required:
      - id
      - access_counter
      - filename
      - content_type
      - download_url
      - expires_at
      - authorizable
      - expired
      - access_limit_exceeded
      x-typelizer: true
    Discount:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        kind:
          type: string
          enum:
          - promotion
          - manual
        code:
          type: string
          nullable: true
        value_type:
          type: string
          nullable: true
        value:
          type: string
          nullable: true
        promotion_id:
          type: string
          nullable: true
        line_item_id:
          type: string
          nullable: true
        fulfillment_id:
          type: string
          nullable: true
        amount:
          type: string
          nullable: true
        display_amount:
          type: string
          nullable: true
      required:
      - id
      - label
      - kind
      - code
      - value_type
      - value
      - promotion_id
      - line_item_id
      - fulfillment_id
      - amount
      - display_amount
      x-typelizer: true
    Fee:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        kind:
          anyOf:
          - type: string
            enum:
            - surcharge
            - handling
            - gift_wrap
            - cod
            - payment
            - duty
          - type: string
          description: What sort of charge this is. `duty` is a customs duty on a
            cross-border order and is not taxed; the other kinds are. Extensions may
            register further kinds.
        line_item_id:
          type: string
          nullable: true
        fulfillment_id:
          type: string
          nullable: true
        amount:
          type: string
          nullable: true
        display_amount:
          type: string
          nullable: true
      required:
      - id
      - label
      - kind
      - line_item_id
      - fulfillment_id
      - amount
      - display_amount
      x-typelizer: true
    FreightSummary:
      type: object
      properties:
        total_units:
          type: number
        total_cartons:
          type: number
        total_pallets:
          type: number
          nullable: true
        total_volume:
          type: string
        total_weight:
          type: string
        complete:
          type: boolean
      required:
      - total_units
      - total_cartons
      - total_pallets
      - total_volume
      - total_weight
      - complete
      x-typelizer: true
    Fulfillment:
      type: object
      properties:
        id:
          type: string
        number:
          type: string
        tracking:
          type: string
          nullable: true
        tracking_url:
          type: string
          nullable: true
        pickup_point_data:
          type: object
          nullable: true
        selected_delivery_rate_id:
          type: string
          nullable: true
        unpriced:
          type: boolean
        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:
          anyOf:
          - type: string
            enum:
            - unfulfilled
            - fulfilled
            - delivered
            - canceled
          - type: string
          description: The values listed are the built-in ones; extensions may add
            more.
        fulfillment_type:
          type: string
          enum:
          - shipping
          - digital
          - pickup
          - pickup_point
        fulfilled_at:
          type: string
          nullable: true
        delivered_at:
          type: string
          nullable: true
        items:
          type: array
          items:
            "$ref": "#/components/schemas/FulfillmentManifestItem"
        deliveries:
          type: array
          items:
            "$ref": "#/components/schemas/Delivery"
        delivery_method:
          "$ref": "#/components/schemas/DeliveryMethod"
        stock_location:
          "$ref": "#/components/schemas/StockLocation"
        delivery_rates:
          type: array
          items:
            "$ref": "#/components/schemas/DeliveryRate"
        tax_lines:
          type: array
          items:
            "$ref": "#/components/schemas/TaxLine"
      required:
      - id
      - number
      - tracking
      - tracking_url
      - pickup_point_data
      - selected_delivery_rate_id
      - unpriced
      - 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
      - delivered_at
      - items
      - deliveries
      - 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:
          anyOf:
          - type: string
            enum:
            - active
            - partially_redeemed
            - redeemed
            - canceled
            - expired
          - type: string
          description: The values listed are the built-in ones; extensions may add
            more.
        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
        created_at:
          type: string
        updated_at:
          type: string
        status:
          anyOf:
          - type: string
            enum:
            - pending
            - accepted
          - type: string
          description: The values listed are the built-in ones; extensions may add
            more.
        resource_type:
          type: string
          nullable: true
        inviter_type:
          type: string
          nullable: true
        invitee_type:
          type: string
          nullable: true
        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
      - created_at
      - updated_at
      - status
      - resource_type
      - inviter_type
      - invitee_type
      - 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
        seller_id:
          type: string
          nullable: true
        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
        seller:
          "$ref": "#/components/schemas/Seller"
        option_values:
          type: array
          items:
            "$ref": "#/components/schemas/OptionValue"
        digital_links:
          type: array
          items:
            "$ref": "#/components/schemas/DigitalLink"
        tax_lines:
          type: array
          items:
            "$ref": "#/components/schemas/TaxLine"
      required:
      - id
      - variant_id
      - seller_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_codes:
          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_codes
      - supported_locales
      x-typelizer: true
    MediaEvent:
      type: object
      properties:
        id:
          type: string
        viewable_id:
          type: string
        viewable_type:
          type: string
        media_type:
          type: string
          enum:
          - image
          - video
          - external_video
        position:
          type: number
          nullable: true
        alt:
          type: string
          nullable: true
        created_at:
          type: string
        updated_at:
          type: string
      required:
      - id
      - viewable_id
      - viewable_type
      - media_type
      - position
      - alt
      - created_at
      - updated_at
      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
          enum:
          - image
          - video
          - external_video
        focal_point_x:
          type: number
          nullable: true
        focal_point_y:
          type: number
          nullable: true
        external_video_url:
          type: string
          nullable: true
        video_provider:
          type: string
          nullable: true
        video_embed_url:
          type: string
          nullable: true
        video_url:
          type: string
          nullable: true
        poster_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
      - video_provider
      - video_embed_url
      - video_url
      - poster_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
          enum:
          - dropdown
          - color_swatch
          - buttons
      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
    OrderGroup:
      type: object
      properties:
        id:
          type: string
        number:
          type: string
        email:
          type: string
          nullable: true
        currency:
          type: string
        total:
          type: string
          nullable: true
        display_total:
          type: string
          nullable: true
        item_total:
          type: string
          nullable: true
        display_item_total:
          type: string
          nullable: true
        fulfillment_status:
          type: string
          nullable: true
          enum:
          - backorder
          - canceled
          - partial
          - unfulfilled
          - fulfilled
          - delivered
          - pending
          - ready
          - shipped
        payment_status:
          type: string
          nullable: true
          enum:
          - none
          - authorized
          - partially_paid
          - paid
          - partially_refunded
          - refunded
          - overcharged
          - voided
        completed_at:
          type: string
          nullable: true
        billing_address:
          allOf:
          - "$ref": "#/components/schemas/Address"
          nullable: true
        shipping_address:
          allOf:
          - "$ref": "#/components/schemas/Address"
          nullable: true
        orders:
          type: array
          items:
            "$ref": "#/components/schemas/Order"
      required:
      - id
      - number
      - email
      - currency
      - total
      - display_total
      - item_total
      - display_item_total
      - fulfillment_status
      - payment_status
      - completed_at
      - billing_address
      - shipping_address
      - orders
      x-typelizer: true
    Order:
      type: object
      properties:
        id:
          type: string
        market_id:
          type: string
          nullable: true
        withdrawal_period_ends_at:
          type: string
          nullable: true
        within_withdrawal_period:
          type: boolean
        cart_id:
          type: string
          nullable: true
        channel_id:
          type: string
          nullable: true
        company_id:
          type: string
          nullable: true
        company_name:
          type: string
          nullable: true
        po_document_filename:
          type: string
          nullable: true
        po_document_byte_size:
          type: number
          nullable: true
        number:
          type: string
        email:
          type: string
        customer_note:
          type: string
          nullable: true
        po_number:
          type: string
          nullable: true
        currency:
          type: string
        locale:
          type: string
          nullable: true
        total_quantity:
          type: number
        coupon_code:
          type: string
          nullable: true
        fulfillment_status:
          type: string
          nullable: true
          enum:
          - backorder
          - canceled
          - partial
          - unfulfilled
          - fulfilled
          - delivered
          - pending
          - ready
          - shipped
        payment_status:
          type: string
          nullable: true
          enum:
          - none
          - authorized
          - partially_paid
          - paid
          - partially_refunded
          - refunded
          - overcharged
          - voided
        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
        fee_total:
          type: string
          nullable: true
        display_fee_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/AppliedPromotion"
        fees:
          type: array
          items:
            "$ref": "#/components/schemas/Fee"
        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
      - withdrawal_period_ends_at
      - within_withdrawal_period
      - cart_id
      - channel_id
      - company_id
      - company_name
      - po_document_filename
      - po_document_byte_size
      - number
      - email
      - customer_note
      - po_number
      - currency
      - locale
      - total_quantity
      - coupon_code
      - 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
      - fee_total
      - display_fee_total
      - store_credit_total
      - display_store_credit_total
      - covered_by_store_credit
      - discounts
      - fees
      - 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
          description: 'Payment method type. Built-in: check, store_credit, custom_payment_source_method,
            bogus (test only); payment provider gems register their own, for example
            stripe.'
        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
        status:
          anyOf:
          - type: string
            enum:
            - checkout
            - processing
            - pending
            - completed
            - failed
            - void
            - invalid
          - type: string
          description: The values listed are the built-in ones; extensions may add
            more.
        amount:
          type: string
          nullable: true
        display_amount:
          type: string
          nullable: true
        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
      - status
      - amount
      - display_amount
      - source_type
      - source_id
      - source
      - payment_method
      x-typelizer: true
    PaymentSession:
      type: object
      properties:
        id:
          type: string
        status:
          anyOf:
          - type: string
            enum:
            - pending
            - processing
            - completed
            - failed
            - canceled
            - expired
          - type: string
          description: The values listed are the built-in ones; extensions may add
            more.
        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
          nullable: true
        cart_id:
          type: string
          nullable: true
        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
      - cart_id
      - payment_method
      x-typelizer: true
    PaymentSetupSession:
      type: object
      properties:
        id:
          type: string
        status:
          anyOf:
          - type: string
            enum:
            - pending
            - processing
            - completed
            - failed
            - canceled
            - expired
          - type: string
          description: The values listed are the built-in ones; extensions may add
            more.
        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
        updated_at:
          type: string
      required:
      - id
      - name
      - slug
      - body
      - body_html
      - updated_at
      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
          enum:
          - dropdown
          - color_swatch
          - buttons
        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
        label:
          type: string
          nullable: true
      required:
      - id
      - label
      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
        buy_box_variant_id:
          type: string
          nullable: true
        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
        seller_id:
          type: string
          nullable: true
        seller:
          "$ref": "#/components/schemas/Seller"
        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
      - buy_box_variant_id
      - thumbnail_url
      - tags
      - price
      - original_price
      - seller_id
      x-typelizer: true
    ProductType:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required:
      - id
      - name
      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
        originator_id:
          type: string
          nullable: true
        originator_type:
          type: string
          nullable: true
      required:
      - id
      - transaction_id
      - amount
      - payment_id
      - refund_reason_id
      - originator_id
      - originator_type
      x-typelizer: true
    ReturnLineItem:
      type: object
      properties:
        id:
          type: string
        quantity:
          type: number
        received_quantity:
          type: number
        resellable:
          type: boolean
        pre_tax_amount:
          type: string
        display_pre_tax_amount:
          type: string
        variant_id:
          type: string
          nullable: true
        line_item_id:
          type: string
          nullable: true
        fulfillment_item_id:
          type: string
          nullable: true
        variant:
          "$ref": "#/components/schemas/Variant"
      required:
      - id
      - quantity
      - received_quantity
      - resellable
      - pre_tax_amount
      - display_pre_tax_amount
      - variant_id
      - line_item_id
      - fulfillment_item_id
      x-typelizer: true
    ReturnReason:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        active:
          type: boolean
      required:
      - id
      - name
      - active
      x-typelizer: true
    Return:
      type: object
      properties:
        id:
          type: string
        number:
          type: string
        status:
          anyOf:
          - type: string
            enum:
            - requested
            - approved
            - received
            - refunded
            - canceled
          - type: string
          description: The values listed are the built-in ones; extensions may add
            more.
        order_id:
          type: string
          nullable: true
        reason_id:
          type: string
          nullable: true
        refund_total:
          type: string
        display_refund_total:
          type: string
        approved_at:
          type: string
          nullable: true
        received_at:
          type: string
          nullable: true
        refunded_at:
          type: string
          nullable: true
        canceled_at:
          type: string
          nullable: true
        reason:
          "$ref": "#/components/schemas/ReturnReason"
        return_line_items:
          type: array
          items:
            "$ref": "#/components/schemas/ReturnLineItem"
      required:
      - id
      - number
      - status
      - order_id
      - reason_id
      - refund_total
      - display_refund_total
      - approved_at
      - received_at
      - refunded_at
      - canceled_at
      x-typelizer: true
    Seller:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        about:
          type: string
        about_html:
          type: string
        logo_url:
          type: string
          nullable: true
        square_logo_url:
          type: string
          nullable: true
        cover_photo_url:
          type: string
          nullable: true
        policies:
          type: array
          items:
            "$ref": "#/components/schemas/Policy"
      required:
      - id
      - name
      - slug
      - about
      - about_html
      - logo_url
      - square_logo_url
      - cover_photo_url
      x-typelizer: true
    ShippingLabelEvent:
      type: object
      properties:
        id:
          type: string
        source:
          type: string
          enum:
          - purchased
          - uploaded
        status:
          anyOf:
          - type: string
            enum:
            - purchased
            - refund_requested
            - refunded
          - type: string
          description: The values listed are the built-in ones; extensions may add
            more.
        carrier:
          type: string
          nullable: true
        carrier_name:
          type: string
          nullable: true
        service:
          type: string
          nullable: true
        tracking_number:
          type: string
          nullable: true
        currency:
          type: string
          nullable: true
        format:
          type: string
          nullable: true
        external_id:
          type: string
          nullable: true
        metadata:
          type: object
        refunded_at:
          type: string
          nullable: true
        created_at:
          type: string
        updated_at:
          type: string
        owner_id:
          type: string
        owner_type:
          type: string
          enum:
          - Spree::Fulfillment
          - Spree::Return
        cost:
          type: string
        display_cost:
          type: string
        integration_id:
          type: string
          nullable: true
        file_pending:
          type: boolean
        download_url:
          type: string
          nullable: true
      required:
      - id
      - source
      - status
      - carrier
      - carrier_name
      - service
      - tracking_number
      - currency
      - format
      - external_id
      - metadata
      - refunded_at
      - created_at
      - updated_at
      - owner_id
      - owner_type
      - cost
      - display_cost
      - integration_id
      - file_pending
      - download_url
      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
        name:
          type: string
        address1:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        zipcode:
          type: string
          nullable: true
        country_code:
          type: string
          nullable: true
        country_name:
          type: string
          nullable: true
        state_code:
          type: string
          nullable: true
        state_text:
          type: string
          nullable: true
        pickup_ready_in_minutes:
          type: number
          nullable: true
        pickup_instructions:
          type: string
          nullable: true
      required:
      - id
      - name
      - address1
      - city
      - zipcode
      - country_code
      - country_name
      - state_code
      - state_text
      - pickup_ready_in_minutes
      - pickup_instructions
      x-typelizer: true
    StockReservation:
      type: object
      properties:
        id:
          type: string
      required:
      - id
      x-typelizer: true
    StoreCreditEvent:
      type: object
      properties:
        id:
          type: string
        action:
          type: string
        authorization_code:
          type: string
          nullable: true
        display_action:
          type: string
          nullable: true
        amount:
          type: string
        display_amount:
          type: string
        created_at:
          type: string
      required:
      - id
      - action
      - authorization_code
      - display_action
      - amount
      - display_amount
      - created_at
      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
    TaxIdentifier:
      type: object
      properties:
        id:
          type: string
        kind:
          type: string
          description: 'Tax identifier kind, keyed to a registered validator. Built-in:
            eu_vat. Extensions may register more.'
        value:
          type: string
      required:
      - id
      - kind
      - value
      x-typelizer: true
    TaxLine:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        included:
          type: boolean
        rate:
          type: string
        tax_rate_id:
          type: string
          nullable: true
        line_item_id:
          type: string
          nullable: true
        fulfillment_id:
          type: string
          nullable: true
        fee_id:
          type: string
          nullable: true
        amount:
          type: string
          nullable: true
        display_amount:
          type: string
          nullable: true
      required:
      - id
      - label
      - included
      - rate
      - tax_rate_id
      - line_item_id
      - fulfillment_id
      - fee_id
      - amount
      - display_amount
      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
        weight_unit:
          type: string
          enum:
          - g
          - kg
          - lb
          - oz
        dimensions_unit:
          type: string
          enum:
          - mm
          - cm
          - in
          - ft
        minimum_order_quantity:
          type: number
        order_multiple:
          type: number
        purchase_unit:
          type: string
          enum:
          - unit
          - carton
        units_per_carton:
          type: number
          nullable: true
        price:
          "$ref": "#/components/schemas/Price"
        original_price:
          allOf:
          - "$ref": "#/components/schemas/Price"
          nullable: true
        seller_id:
          type: string
          nullable: true
        seller:
          "$ref": "#/components/schemas/Seller"
        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
      - weight_unit
      - dimensions_unit
      - minimum_order_quantity
      - order_multiple
      - purchase_unit
      - units_per_carton
      - price
      - original_price
      - seller_id
      - 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