---
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.

        Dispatches by the `provider` field to a strategy registered in
        `Spree.store_authentication_strategies`. When `provider` is omitted it
        defaults to `email`, which uses the built-in email/password strategy.

        To plug in a third-party identity provider (Auth0, Okta, Firebase, a
        custom JWT issuer, SAML, etc.), register a `Spree::Authentication::Strategies::BaseStrategy`
        subclass under a provider key, then send `{ "provider": "<your_key>", ... }`
        with the fields your strategy requires. The endpoint returns the same
        Spree-issued JWT + refresh token regardless of which strategy authenticated
        the request.
      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.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjY0NjcwM2Q0LWY5ZjAtNDlmMi05ZmZkLTA3YTZhY2I5YWZkZiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc5ODE1NjE1fQ.jlz2KHxYkB1Dd9ucl26zy6E5M7dFB5q9g-Qw0YjsX50
                refresh_token: MQ9QZ1ToR8QocZoDd4ggC8yN
                user:
                  id: cus_UkLWZg9DAJ
                  email: test@example.com
                  first_name: Colette
                  last_name: Hegmann
                  phone:
                  accepts_email_marketing: false
                  full_name: Colette Hegmann
                  available_store_credit_total: '0'
                  display_available_store_credit_total: "$0.00"
                  addresses: []
                  default_billing_address:
                  default_shipping_address:
              schema:
                "$ref": "#/components/schemas/AuthResponse"
        '401':
          description: missing API key
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: Valid API key required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              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 registered
                  strategy class; the remaining fields are forwarded to the strategy's
                  `authenticate` method. Required fields depend on the registered strategy
                  — consult its documentation.
                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.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjNmZjU3NWU0LTVmNmItNDVjOC04MzIzLTIzMDMyMzVjZTkzMiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc5ODE1NjE2fQ.OuCk-UNe-asA8DvK2yKMkp94BQz9PN_Z7_SnReeIRYE
                refresh_token: qLuZDRo8LqywXFThqPM5V2Ug
                user:
                  id: cus_UkLWZg9DAJ
                  email: test@example.com
                  first_name: Debi
                  last_name: Tillman
                  phone:
                  accepts_email_marketing: false
                  full_name: Debi Tillman
                  available_store_credit_total: '0'
                  display_available_store_credit_total: "$0.00"
                  addresses: []
                  default_billing_address:
                  default_shipping_address:
              schema:
                "$ref": "#/components/schemas/AuthResponse"
        '401':
          description: missing or invalid refresh token
          content:
            application/json:
              example:
                error:
                  code: invalid_refresh_token
                  message: Invalid or expired refresh token
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                refresh_token:
                  type: string
                  description: Refresh token from login response
              required:
              - refresh_token
  "/api/v3/store/auth/logout":
    post:
      summary: Logout
      tags:
      - Authentication
      security:
      - api_key: []
      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.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjU1YjA5Yzc4LTUzMTYtNDRjYy05ZjJiLThmN2E2MzViMmRlNSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc5ODE1NjI4fQ.FX2Te4WfdAu3kN_fvvfHsH92_axvIZTI1d8Zmw8R1mE
                refresh_token: Be2HUCjiJVRjgidFuYU7GRRh
                user:
                  id: cus_UkLWZg9DAJ
                  email: customer@example.com
                  first_name: Randa
                  last_name: O'Hara
                  phone:
                  accepts_email_marketing: false
                  full_name: Randa O'Hara
                  available_store_credit_total: '0'
                  display_available_store_credit_total: "$0.00"
                  addresses: []
                  default_billing_address:
                  default_shipping_address:
              schema:
                "$ref": "#/components/schemas/AuthResponse"
        '422':
          description: password confirmation mismatch
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Password confirmation doesn't match Password
                  details:
                    password_confirmation:
                    - doesn't match Password
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '401':
          description: missing API key
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: Valid API key required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  type: string
                  minLength: 6
                  example: newsecurepassword
                password_confirmation:
                  type: string
                  example: newsecurepassword
              required:
              - password
              - password_confirmation
  "/api/v3/store/categories":
    get:
      summary: List categories
      tags:
      - Product Catalog
      security:
      - api_key: []
      description: Returns a paginated list of categories for the current store
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

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

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

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

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

          const products = await client.products.list({
            page: 1,
            limit: 25,
            sort: 'price',
            name_cont: 'shirt',
            price_gte: 20,
            price_lte: 100,
            with_option_value_ids: ['optval_abc', 'optval_def'],
            expand: ['variants', 'media'],
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        description: Publishable API key
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: 'Page number (default: 1)'
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: 'Number of items per page (default: 25, max: 100)'
        schema:
          type: integer
      - name: sort
        in: query
        required: false
        description: 'Sort order. Prefix with - for descending. Values: price, -price,
          best_selling, name, -name, -available_on, available_on'
        schema:
          type: string
      - name: q[name_cont]
        in: query
        required: false
        description: Filter by name containing string
        schema:
          type: string
      - name: q[in_category]
        in: query
        required: false
        description: Filter by category prefixed ID (includes descendants)
        schema:
          type: string
      - name: q[in_categories][]
        in: query
        required: false
        description: Filter by multiple category prefixed IDs (OR logic, includes
          descendants)
        schema:
          type: string
      - name: q[price_gte]
        in: query
        required: false
        description: Filter by minimum price
        schema:
          type: number
      - name: q[price_lte]
        in: query
        required: false
        description: Filter by maximum price
        schema:
          type: number
      - name: q[with_option_value_ids][]
        in: query
        required: false
        description: Filter by option value prefix IDs (e.g., optval_abc). Pass multiple
          values for OR logic.
        schema:
          type: string
      - name: q[in_stock]
        in: query
        required: false
        description: Filter to only in-stock products
        schema:
          type: boolean
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (variants, media, categories,
          option_types)
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: products found
          content:
            application/json:
              example:
                data:
                - id: prod_UkLWZg9DAJ
                  name: Product 1421251
                  slug: product-1421251
                  meta_title:
                  meta_description:
                  meta_keywords:
                  variant_count: 1
                  available_on: '2025-05-26T16:14:22.402Z'
                  purchasable: true
                  in_stock: false
                  backorderable: true
                  available: true
                  description: A comfortable cotton t-shirt.
                  description_html: "<p>A <strong>comfortable</strong> cotton t-shirt.</p>"
                  default_variant_id: variant_gbHJdmfrXB
                  thumbnail_url:
                  tags: []
                  price:
                    id: price_gbHJdmfrXB
                    amount: '19.99'
                    amount_in_cents: 1999
                    compare_at_amount:
                    compare_at_amount_in_cents:
                    currency: USD
                    display_amount: "$19.99"
                    display_compare_at_amount:
                    price_list_id:
                  original_price:
                - id: prod_gbHJdmfrXB
                  name: Product 1435220
                  slug: product-1435220
                  meta_title:
                  meta_description:
                  meta_keywords:
                  variant_count: 0
                  available_on: '2025-05-26T16:14:22.472Z'
                  purchasable: true
                  in_stock: false
                  backorderable: true
                  available: true
                  description: Architecto dignissimos nemo inventore incidunt enim.
                    Odit accusamus repellat error saepe culpa unde eius. Cupiditate
                    officiis voluptatem autem perferendis qui vitae omnis sunt. Debitis
                    dolor tempore ad impedit itaque reprehenderit delectus. Doloremque
                    laudantium iure recusandae iusto debitis laborum consequuntur.
                    Impedit eum optio commodi tempora cum quidem. Facere voluptatum
                    nam possimus veritatis nostrum explicabo dolore ex. Adipisci iure
                    unde nobis itaque amet nesciunt voluptatibus impedit. Numquam
                    in accusantium magni itaque exercitationem. Quas vero maxime voluptatem
                    rem impedit inventore. Esse perferendis asperiores ea expedita
                    aut tenetur soluta. Enim accusantium dolor adipisci impedit. Error
                    maxime neque accusamus facere provident eum. Cum officia velit
                    asperiores quod cupiditate fugiat. Possimus tenetur aut consequuntur
                    iusto cumque quas. Ab velit ullam qui pariatur veritatis omnis.
                    Accusantium vero occaecati explicabo neque animi commodi. Necessitatibus
                    perspiciatis iste culpa totam quibusdam voluptate distinctio.
                    Quod aliquam ut et autem. Saepe ut asperiores et quisquam perspiciatis
                    molestiae. Vel recusandae sunt nemo et accusamus veniam ducimus.
                    Laborum modi quasi perferendis culpa laboriosam quaerat magnam.
                    Facere at tempora iusto ex magni aliquam modi debitis.
                  description_html: |-
                    Architecto dignissimos nemo inventore incidunt enim. Odit accusamus repellat error saepe culpa unde eius. Cupiditate officiis voluptatem autem perferendis qui vitae omnis sunt. Debitis dolor tempore ad impedit itaque reprehenderit delectus. Doloremque laudantium iure recusandae iusto debitis laborum consequuntur.
                    Impedit eum optio commodi tempora cum quidem. Facere voluptatum nam possimus veritatis nostrum explicabo dolore ex. Adipisci iure unde nobis itaque amet nesciunt voluptatibus impedit. Numquam in accusantium magni itaque exercitationem. Quas vero maxime voluptatem rem impedit inventore.
                    Esse perferendis asperiores ea expedita aut tenetur soluta. Enim accusantium dolor adipisci impedit. Error maxime neque accusamus facere provident eum. Cum officia velit asperiores quod cupiditate fugiat. Possimus tenetur aut consequuntur iusto cumque quas.
                    Ab velit ullam qui pariatur veritatis omnis. Accusantium vero occaecati explicabo neque animi commodi. Necessitatibus perspiciatis iste culpa totam quibusdam voluptate distinctio. Quod aliquam ut et autem. Saepe ut asperiores et quisquam perspiciatis molestiae.
                    Vel recusandae sunt nemo et accusamus veniam ducimus. Laborum modi quasi perferendis culpa laboriosam quaerat magnam. Facere at tempora iusto ex magni aliquam modi debitis.
                  default_variant_id: variant_EfhxLZ9ck8
                  thumbnail_url:
                  tags: []
                  price:
                    id: price_EfhxLZ9ck8
                    amount: '19.99'
                    amount_in_cents: 1999
                    compare_at_amount:
                    compare_at_amount_in_cents:
                    currency: USD
                    display_amount: "$19.99"
                    display_compare_at_amount:
                    price_list_id:
                  original_price:
                meta:
                  page: 1
                  limit: 25
                  count: 2
                  pages: 1
                  from: 1
                  to: 2
                  in: 2
                  previous:
                  next:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Product"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
        '401':
          description: unauthorized - invalid or missing API key
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: Valid API key required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/products/{id}":
    get:
      summary: Get a product
      tags:
      - Product Catalog
      security:
      - api_key: []
      description: Returns a single product by slug or prefix ID
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

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

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

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

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

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

          const carts = await client.carts.list({
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: 'Page number (default: 1)'
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: 'Number of results per page (default: 25, max: 100)'
        schema:
          type: integer
      - name: sort
        in: query
        required: false
        description: 'Sort order. Prefix with - for descending. Values: created_at,
          -created_at, updated_at, -updated_at'
        schema:
          type: string
      - name: q[created_at_gt]
        in: query
        required: false
        description: Filter by created after date (ISO 8601)
        schema:
          type: string
      - name: q[updated_at_gt]
        in: query
        required: false
        description: Filter by updated after date (ISO 8601)
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (items, fulfillments,
          payments, discounts, billing_address, shipping_address, gift_card, payment_methods).
          Use "none" to skip associations.
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., total,amount_due,item_count).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: carts listed
          content:
            application/json:
              example:
                data:
                - id: cart_gbHJdmfrXB
                  market_id:
                  number: R537347983
                  token: yasKz5u5Uc9LkM8L2qFcbBRhWQzwP1nNUBe
                  email: orval_boyle@abernathybogisich.co.uk
                  customer_note:
                  currency: USD
                  locale: en
                  total_quantity: 1
                  item_total: '10.0'
                  display_item_total: "$10.00"
                  adjustment_total: '0.0'
                  display_adjustment_total: "$0.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  tax_total: '0.0'
                  display_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  total: '110.0'
                  display_total: "$110.00"
                  gift_card_total: '0.0'
                  display_gift_card_total: "$0.00"
                  amount_due: '110.0'
                  display_amount_due: "$110.00"
                  delivery_total: '100.0'
                  display_delivery_total: "$100.00"
                  warnings: []
                  store_credit_total: '0.0'
                  display_store_credit_total: "$0.00"
                  covered_by_store_credit: false
                  current_step: address
                  completed_steps: []
                  requirements:
                  - step: payment
                    field: payment
                    message: Add a payment method
                  shipping_eq_billing_address: false
                  discounts: []
                  items:
                  - id: li_gbHJdmfrXB
                    variant_id: variant_gbHJdmfrXB
                    quantity: 1
                    currency: USD
                    name: Product 832050
                    slug: product-832050
                    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: H02359090617
                    tracking: U10000
                    tracking_url:
                    cost: '100.0'
                    display_cost: "$100.00"
                    total: '100.0'
                    display_total: "$100.00"
                    discount_total: '0.0'
                    display_discount_total: "$0.00"
                    additional_tax_total: '0.0'
                    display_additional_tax_total: "$0.00"
                    included_tax_total: '0.0'
                    display_included_tax_total: "$0.00"
                    tax_total: '0.0'
                    display_tax_total: "$0.00"
                    status: pending
                    fulfillment_type: shipping
                    fulfilled_at:
                    items:
                    - item_id: li_gbHJdmfrXB
                      variant_id: variant_gbHJdmfrXB
                      quantity: 1
                    delivery_method:
                      id: dm_gbHJdmfrXB
                      name: UPS Ground
                      code: UPS_GROUND
                    stock_location:
                      id: sloc_UkLWZg9DAJ
                      state_abbr: NY
                      name: Blair Moore
                      address1: 1600 Pennsylvania Ave NW
                      city: Washington
                      zipcode: '20500'
                      country_iso: US
                      country_name: United States of America
                      state_text: NY
                    delivery_rates:
                    - id: dr_gbHJdmfrXB
                      delivery_method_id: dm_gbHJdmfrXB
                      name: UPS Ground
                      selected: true
                      cost: '100.0'
                      total: '100.0'
                      additional_tax_total: '0.0'
                      included_tax_total: '0.0'
                      tax_total: '0.0'
                      display_cost: "$100.00"
                      display_total: "$100.00"
                      display_additional_tax_total: "$0.00"
                      display_included_tax_total: "$0.00"
                      display_tax_total: "$0.00"
                      delivery_method:
                        id: dm_gbHJdmfrXB
                        name: UPS Ground
                        code: UPS_GROUND
                  payments: []
                  billing_address:
                    id: addr_uw2YK1rnl0
                    first_name: John
                    last_name: Doe
                    full_name: John Doe
                    address1: 101 Lovely Street
                    address2: Northwest
                    postal_code: '10118'
                    city: New York
                    phone: 555-555-0199
                    company: Company
                    country_name: United States of America
                    country_iso: US
                    state_text: NY
                    state_abbr: NY
                    quick_checkout: false
                    is_default_billing: false
                    is_default_shipping: false
                    state_name: New York
                  shipping_address:
                    id: addr_OIJLhNcSbf
                    first_name: John
                    last_name: Doe
                    full_name: John Doe
                    address1: 102 Lovely Street
                    address2: Northwest
                    postal_code: '10118'
                    city: New York
                    phone: 555-555-0199
                    company: Company
                    country_name: United States of America
                    country_iso: US
                    state_text: NY
                    state_abbr: NY
                    quick_checkout: false
                    is_default_billing: false
                    is_default_shipping: false
                    state_name: New York
                  payment_methods: []
                  gift_card:
                  market:
                - id: cart_UkLWZg9DAJ
                  market_id:
                  number: R807784030
                  token: nXX7y8d9LZ1UXEmP8CxfE2vvLYZH9s6K9Y3
                  email: orval_boyle@abernathybogisich.co.uk
                  customer_note:
                  currency: USD
                  locale: en
                  total_quantity: 1
                  item_total: '10.0'
                  display_item_total: "$10.00"
                  adjustment_total: '0.0'
                  display_adjustment_total: "$0.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  tax_total: '0.0'
                  display_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  total: '110.0'
                  display_total: "$110.00"
                  gift_card_total: '0.0'
                  display_gift_card_total: "$0.00"
                  amount_due: '110.0'
                  display_amount_due: "$110.00"
                  delivery_total: '100.0'
                  display_delivery_total: "$100.00"
                  warnings: []
                  store_credit_total: '0'
                  display_store_credit_total: "$0.00"
                  covered_by_store_credit: false
                  current_step: address
                  completed_steps: []
                  requirements:
                  - step: payment
                    field: payment
                    message: Add a payment method
                  shipping_eq_billing_address: false
                  discounts: []
                  items:
                  - id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                    currency: USD
                    name: Product 821901
                    slug: product-821901
                    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: H10388427867
                    tracking: U10000
                    tracking_url:
                    cost: '100.0'
                    display_cost: "$100.00"
                    total: '100.0'
                    display_total: "$100.00"
                    discount_total: '0.0'
                    display_discount_total: "$0.00"
                    additional_tax_total: '0.0'
                    display_additional_tax_total: "$0.00"
                    included_tax_total: '0.0'
                    display_included_tax_total: "$0.00"
                    tax_total: '0.0'
                    display_tax_total: "$0.00"
                    status: pending
                    fulfillment_type: shipping
                    fulfilled_at:
                    items:
                    - item_id: li_UkLWZg9DAJ
                      variant_id: variant_UkLWZg9DAJ
                      quantity: 1
                    delivery_method:
                      id: dm_UkLWZg9DAJ
                      name: UPS Ground
                      code: UPS_GROUND
                    stock_location:
                      id: sloc_UkLWZg9DAJ
                      state_abbr: NY
                      name: Blair Moore
                      address1: 1600 Pennsylvania Ave NW
                      city: Washington
                      zipcode: '20500'
                      country_iso: US
                      country_name: United States of America
                      state_text: NY
                    delivery_rates:
                    - id: dr_UkLWZg9DAJ
                      delivery_method_id: dm_UkLWZg9DAJ
                      name: UPS Ground
                      selected: true
                      cost: '100.0'
                      total: '100.0'
                      additional_tax_total: '0.0'
                      included_tax_total: '0.0'
                      tax_total: '0.0'
                      display_cost: "$100.00"
                      display_total: "$100.00"
                      display_additional_tax_total: "$0.00"
                      display_included_tax_total: "$0.00"
                      display_tax_total: "$0.00"
                      delivery_method:
                        id: dm_UkLWZg9DAJ
                        name: UPS Ground
                        code: UPS_GROUND
                  payments: []
                  billing_address:
                    id: addr_EfhxLZ9ck8
                    first_name: John
                    last_name: Doe
                    full_name: John Doe
                    address1: 99 Lovely Street
                    address2: Northwest
                    postal_code: '10118'
                    city: New York
                    phone: 555-555-0199
                    company: Company
                    country_name: United States of America
                    country_iso: US
                    state_text: NY
                    state_abbr: NY
                    quick_checkout: false
                    is_default_billing: false
                    is_default_shipping: false
                    state_name: New York
                  shipping_address:
                    id: addr_VqXmZF31wY
                    first_name: John
                    last_name: Doe
                    full_name: John Doe
                    address1: 100 Lovely Street
                    address2: Northwest
                    postal_code: '10118'
                    city: New York
                    phone: 555-555-0199
                    company: Company
                    country_name: United States of America
                    country_iso: US
                    state_text: NY
                    state_abbr: NY
                    quick_checkout: false
                    is_default_billing: false
                    is_default_shipping: false
                    state_name: New York
                  payment_methods: []
                  gift_card:
                  market:
                meta:
                  page: 1
                  limit: 25
                  count: 2
                  pages: 1
                  from: 1
                  to: 2
                  in: 2
                  previous:
                  next:
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    post:
      summary: Create a new cart
      tags:
      - Carts
      security:
      - api_key: []
      description: |
        Creates a new shopping cart. Can be created by guests or authenticated customers.
        Returns a `token` that must be used for guest access to the cart.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

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

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

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

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

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

          const cart = await client.carts.update('cart_abc123', {
            email: 'customer@example.com',
            shipping_address: {
              first_name: 'John',
              last_name: 'Doe',
              address1: '123 Main St',
              city: 'New York',
              postal_code: '10001',
              country_iso: 'US',
              state_abbr: 'NY',
            },
          }, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: cart updated
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R179766659
                token: LwvBFt69BRKiAP4yjrdydKDiefspHrgEEWV
                email: floria_corkery@heaney.com
                customer_note: Leave at door
                currency: USD
                locale: en
                total_quantity: 1
                item_total: '19.99'
                display_item_total: "$19.99"
                adjustment_total: '0.0'
                display_adjustment_total: "$0.00"
                discount_total: '0.0'
                display_discount_total: "$0.00"
                tax_total: '0.0'
                display_tax_total: "$0.00"
                included_tax_total: '0.0'
                display_included_tax_total: "$0.00"
                additional_tax_total: '0.0'
                display_additional_tax_total: "$0.00"
                total: '29.99'
                display_total: "$29.99"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '29.99'
                display_amount_due: "$29.99"
                delivery_total: '10.0'
                display_delivery_total: "$10.00"
                warnings: []
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                current_step: payment
                completed_steps:
                - address
                - delivery
                requirements:
                - step: payment
                  field: payment
                  message: Add a payment method
                shipping_eq_billing_address: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 888308
                  slug: product-888308
                  options_text: ''
                  price: '19.99'
                  display_price: "$19.99"
                  total: '19.99'
                  display_total: "$19.99"
                  adjustment_total: '0.0'
                  display_adjustment_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  pre_tax_amount: '19.99'
                  display_pre_tax_amount: "$19.99"
                  discounted_amount: '19.99'
                  display_discounted_amount: "$19.99"
                  display_compare_at_amount: "$0.00"
                  compare_at_amount:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments:
                - id: ful_gbHJdmfrXB
                  number: H67729784924
                  tracking:
                  tracking_url:
                  cost: '10.0'
                  display_cost: "$10.00"
                  total: '10.0'
                  display_total: "$10.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  tax_total: '0.0'
                  display_tax_total: "$0.00"
                  status: pending
                  fulfillment_type: shipping
                  fulfilled_at:
                  items:
                  - item_id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                  delivery_method:
                    id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    code: UPS_GROUND
                  stock_location:
                    id: sloc_UkLWZg9DAJ
                    state_abbr: NY
                    name: Corazon Luettgen
                    address1: 1600 Pennsylvania Ave NW
                    city: Washington
                    zipcode: '20500'
                    country_iso: US
                    country_name: United States of America
                    state_text: NY
                  delivery_rates:
                  - id: dr_gbHJdmfrXB
                    delivery_method_id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    selected: true
                    cost: '10.0'
                    total: '10.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    display_cost: "$10.00"
                    display_total: "$10.00"
                    display_additional_tax_total: "$0.00"
                    display_included_tax_total: "$0.00"
                    display_tax_total: "$0.00"
                    delivery_method:
                      id: dm_UkLWZg9DAJ
                      name: UPS Ground
                      code: UPS_GROUND
                payments: []
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 113 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                shipping_address:
                  id: addr_VqXmZF31wY
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 114 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                payment_methods: []
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  example: customer@example.com
                customer_note:
                  type: string
                  example: Leave at door
                metadata:
                  type: object
                  additionalProperties: true
                shipping_address_id:
                  type: string
                  description: Existing address ID to use as shipping address
                  example: addr_abc123
                billing_address_id:
                  type: string
                  description: Existing address ID to use as billing address
                  example: addr_def456
                billing_address:
                  type: object
                  properties:
                    first_name:
                      type: string
                    last_name:
                      type: string
                    address1:
                      type: string
                    address2:
                      type: string
                    city:
                      type: string
                    postal_code:
                      type: string
                    phone:
                      type: string
                    company:
                      type: string
                    country_iso:
                      type: string
                    state_abbr:
                      type: string
                shipping_address:
                  type: object
                  properties:
                    first_name:
                      type: string
                    last_name:
                      type: string
                    address1:
                      type: string
                    address2:
                      type: string
                    city:
                      type: string
                    postal_code:
                      type: string
                    phone:
                      type: string
                    company:
                      type: string
                    country_iso:
                      type: string
                    state_abbr:
                      type: string
    delete:
      summary: Delete a cart
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Deletes/abandons the cart.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

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

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

          const cart = await client.carts.associate('cart_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: cart associated successfully
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R741424210
                token: BjQx3Mm7YsM51uEQTvTjE4Jkc9QKpdQ57A4
                email: robbyn@thielkoepp.biz
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                item_total: '10.0'
                display_item_total: "$10.00"
                adjustment_total: '0.0'
                display_adjustment_total: "$0.00"
                discount_total: '0.0'
                display_discount_total: "$0.00"
                tax_total: '0.0'
                display_tax_total: "$0.00"
                included_tax_total: '0.0'
                display_included_tax_total: "$0.00"
                additional_tax_total: '0.0'
                display_additional_tax_total: "$0.00"
                total: '110.0'
                display_total: "$110.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '110.0'
                display_amount_due: "$110.00"
                delivery_total: '100.0'
                display_delivery_total: "$100.00"
                warnings: []
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                current_step: address
                completed_steps: []
                requirements:
                - step: payment
                  field: payment
                  message: Add a payment method
                shipping_eq_billing_address: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 907994
                  slug: product-907994
                  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: H95245243522
                  tracking: U10000
                  tracking_url:
                  cost: '100.0'
                  display_cost: "$100.00"
                  total: '100.0'
                  display_total: "$100.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  tax_total: '0.0'
                  display_tax_total: "$0.00"
                  status: pending
                  fulfillment_type: shipping
                  fulfilled_at:
                  items:
                  - item_id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                  delivery_method:
                    id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    code: UPS_GROUND
                  stock_location:
                    id: sloc_UkLWZg9DAJ
                    state_abbr: NY
                    name: Agatha Hoppe
                    address1: 1600 Pennsylvania Ave NW
                    city: Washington
                    zipcode: '20500'
                    country_iso: US
                    country_name: United States of America
                    state_text: NY
                  delivery_rates:
                  - id: dr_UkLWZg9DAJ
                    delivery_method_id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    selected: true
                    cost: '100.0'
                    total: '100.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    display_cost: "$100.00"
                    display_total: "$100.00"
                    display_additional_tax_total: "$0.00"
                    display_included_tax_total: "$0.00"
                    display_tax_total: "$0.00"
                    delivery_method:
                      id: dm_UkLWZg9DAJ
                      name: UPS Ground
                      code: UPS_GROUND
                payments: []
                billing_address:
                  id: addr_UkLWZg9DAJ
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 119 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                shipping_address:
                  id: addr_gbHJdmfrXB
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 120 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                payment_methods: []
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
        '401':
          description: unauthorized - JWT required
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/carts/{id}/complete":
    post:
      summary: Complete cart
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Completes the cart and finalizes the purchase. Returns an Order
        (not Cart).
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

          const order = await client.carts.complete('cart_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: cart completed
          content:
            application/json:
              example:
                id: or_UkLWZg9DAJ
                market_id:
                channel_id: ch_UkLWZg9DAJ
                number: R464982887
                email: laila@okuneva.co.uk
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                item_total: '19.99'
                display_item_total: "$19.99"
                adjustment_total: '0.0'
                display_adjustment_total: "$0.00"
                discount_total: '0.0'
                display_discount_total: "$0.00"
                tax_total: '0.0'
                display_tax_total: "$0.00"
                included_tax_total: '0.0'
                display_included_tax_total: "$0.00"
                additional_tax_total: '0.0'
                display_additional_tax_total: "$0.00"
                total: '29.99'
                display_total: "$29.99"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '0.0'
                display_amount_due: "$0.00"
                delivery_total: '10.0'
                display_delivery_total: "$10.00"
                fulfillment_status: backorder
                payment_status: paid
                completed_at: '2026-05-26T16:13:41.957Z'
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 924411
                  slug: product-924411
                  options_text: ''
                  price: '19.99'
                  display_price: "$19.99"
                  total: '19.99'
                  display_total: "$19.99"
                  adjustment_total: '0.0'
                  display_adjustment_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  pre_tax_amount: '19.99'
                  display_pre_tax_amount: "$19.99"
                  discounted_amount: '19.99'
                  display_discounted_amount: "$19.99"
                  display_compare_at_amount: "$0.00"
                  compare_at_amount:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments:
                - id: ful_gbHJdmfrXB
                  number: H02978405768
                  tracking:
                  tracking_url:
                  cost: '10.0'
                  display_cost: "$10.00"
                  total: '10.0'
                  display_total: "$10.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  tax_total: '0.0'
                  display_tax_total: "$0.00"
                  status: pending
                  fulfillment_type: shipping
                  fulfilled_at:
                  items:
                  - item_id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                  delivery_method:
                    id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    code: UPS_GROUND
                  stock_location:
                    id: sloc_UkLWZg9DAJ
                    state_abbr: NY
                    name: Zachery Smith
                    address1: 1600 Pennsylvania Ave NW
                    city: Washington
                    zipcode: '20500'
                    country_iso: US
                    country_name: United States of America
                    state_text: NY
                  delivery_rates:
                  - id: dr_gbHJdmfrXB
                    delivery_method_id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    selected: true
                    cost: '10.0'
                    total: '10.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    display_cost: "$10.00"
                    display_total: "$10.00"
                    display_additional_tax_total: "$0.00"
                    display_included_tax_total: "$0.00"
                    display_tax_total: "$0.00"
                    delivery_method:
                      id: dm_UkLWZg9DAJ
                      name: UPS Ground
                      code: UPS_GROUND
                payments:
                - id: py_UkLWZg9DAJ
                  payment_method_id: pm_UkLWZg9DAJ
                  response_code: BGS-176dea87fe0d
                  number: PYQMKAGA
                  amount: '29.99'
                  display_amount: "$29.99"
                  status: completed
                  source_type: credit_card
                  source_id: card_UkLWZg9DAJ
                  source:
                    id: card_UkLWZg9DAJ
                    brand: visa
                    last4: '1111'
                    month: 12
                    year: 2027
                    name: Spree Commerce
                    default: false
                    gateway_payment_profile_id:
                  payment_method:
                    id: pm_UkLWZg9DAJ
                    name: Check
                    description:
                    type: check
                    session_required: false
                    source_required: false
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 127 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                shipping_address:
                  id: addr_VqXmZF31wY
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 128 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Order"
        '422':
          description: cannot complete
          content:
            application/json:
              example:
                error:
                  code: cart_cannot_complete
                  message: No payment found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/carts/{cart_id}/discount_codes":
    post:
      summary: Apply discount code
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: |
        Applies a promotion discount code to the cart. The code is matched case-insensitively.

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

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

          const cart = await client.carts.discountCodes.apply('cart_abc123', 'SAVE10', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        description: Bearer token for authenticated customers
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        description: Order token for guest access
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID (e.g., cart_abc123)
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: Unique key for request idempotency.
        schema:
          type: string
      responses:
        '201':
          description: discount code applied
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R549797108
                token: dtJjZuWMLKEesDsMRZvLQQgWuYY9MuUwL2U
                email: jadwiga@dubuque.name
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                item_total: '10.0'
                display_item_total: "$10.00"
                adjustment_total: "-10.0"
                display_adjustment_total: "-$10.00"
                discount_total: "-10.0"
                display_discount_total: "-$10.00"
                tax_total: '0.0'
                display_tax_total: "$0.00"
                included_tax_total: '0.0'
                display_included_tax_total: "$0.00"
                additional_tax_total: '0.0'
                display_additional_tax_total: "$0.00"
                total: '100.0'
                display_total: "$100.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '100.0'
                display_amount_due: "$100.00"
                delivery_total: '100.0'
                display_delivery_total: "$100.00"
                warnings: []
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                current_step: address
                completed_steps: []
                requirements:
                - step: payment
                  field: payment
                  message: Add a payment method
                shipping_eq_billing_address: false
                discounts:
                - id: discount_UkLWZg9DAJ
                  promotion_id: promo_UkLWZg9DAJ
                  name: Promo
                  description:
                  code: save10
                  amount: "-10.0"
                  display_amount: "-$10.00"
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 1111931
                  slug: product-1111931
                  options_text: ''
                  price: '10.0'
                  display_price: "$10.00"
                  total: '0.0'
                  display_total: "$0.00"
                  adjustment_total: "-10.0"
                  display_adjustment_total: "-$10.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  discount_total: "-10.0"
                  display_discount_total: "-$10.00"
                  pre_tax_amount: '10.0'
                  display_pre_tax_amount: "$10.00"
                  discounted_amount: '0.0'
                  display_discounted_amount: "$0.00"
                  display_compare_at_amount: "$0.00"
                  compare_at_amount:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments:
                - id: ful_UkLWZg9DAJ
                  number: H10253682077
                  tracking: U10000
                  tracking_url:
                  cost: '100.0'
                  display_cost: "$100.00"
                  total: '100.0'
                  display_total: "$100.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  tax_total: '0.0'
                  display_tax_total: "$0.00"
                  status: pending
                  fulfillment_type: shipping
                  fulfilled_at:
                  items:
                  - item_id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                  delivery_method:
                    id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    code: UPS_GROUND
                  stock_location:
                    id: sloc_UkLWZg9DAJ
                    state_abbr: NY
                    name: Clark Gerlach
                    address1: 1600 Pennsylvania Ave NW
                    city: Washington
                    zipcode: '20500'
                    country_iso: US
                    country_name: United States of America
                    state_text: NY
                  delivery_rates:
                  - id: dr_UkLWZg9DAJ
                    delivery_method_id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    selected: true
                    cost: '100.0'
                    total: '100.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    display_cost: "$100.00"
                    display_total: "$100.00"
                    display_additional_tax_total: "$0.00"
                    display_included_tax_total: "$0.00"
                    display_tax_total: "$0.00"
                    delivery_method:
                      id: dm_UkLWZg9DAJ
                      name: UPS Ground
                      code: UPS_GROUND
                payments: []
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 179 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                shipping_address:
                  id: addr_VqXmZF31wY
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 180 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                payment_methods: []
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
        '422':
          description: invalid discount code
          content:
            application/json:
              example:
                error:
                  code: processing_error
                  message: The coupon code you entered doesn't exist. Please try again.
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                  example: SAVE10
                  description: Promotion discount code to apply
              required:
              - code
  "/api/v3/store/carts/{cart_id}/discount_codes/{id}":
    delete:
      summary: Remove discount code
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Removes a previously applied discount code from the cart. The ID
        is the discount code string itself.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

          const cart = await client.carts.discountCodes.remove('cart_abc123', 'SAVE10', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        description: Bearer token for authenticated customers
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: The discount code string to remove (e.g., SAVE10)
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        description: Order token for guest access
        schema:
          type: string
      responses:
        '200':
          description: discount code removed
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R750836348
                token: uesByPtiBKoM7CoRrEKxrNXDHDLP4WQHVEg
                email: earlean@fay.ca
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                item_total: '10.0'
                display_item_total: "$10.00"
                adjustment_total: '0.0'
                display_adjustment_total: "$0.00"
                discount_total: '0.0'
                display_discount_total: "$0.00"
                tax_total: '0.0'
                display_tax_total: "$0.00"
                included_tax_total: '0.0'
                display_included_tax_total: "$0.00"
                additional_tax_total: '0.0'
                display_additional_tax_total: "$0.00"
                total: '110.0'
                display_total: "$110.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '110.0'
                display_amount_due: "$110.00"
                delivery_total: '100.0'
                display_delivery_total: "$100.00"
                warnings: []
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                current_step: address
                completed_steps: []
                requirements:
                - step: payment
                  field: payment
                  message: Add a payment method
                shipping_eq_billing_address: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 1136391
                  slug: product-1136391
                  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: H71965274390
                  tracking: U10000
                  tracking_url:
                  cost: '100.0'
                  display_cost: "$100.00"
                  total: '100.0'
                  display_total: "$100.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  tax_total: '0.0'
                  display_tax_total: "$0.00"
                  status: pending
                  fulfillment_type: shipping
                  fulfilled_at:
                  items:
                  - item_id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                  delivery_method:
                    id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    code: UPS_GROUND
                  stock_location:
                    id: sloc_UkLWZg9DAJ
                    state_abbr: NY
                    name: Drusilla Greenfelder
                    address1: 1600 Pennsylvania Ave NW
                    city: Washington
                    zipcode: '20500'
                    country_iso: US
                    country_name: United States of America
                    state_text: NY
                  delivery_rates:
                  - id: dr_UkLWZg9DAJ
                    delivery_method_id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    selected: true
                    cost: '100.0'
                    total: '100.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    display_cost: "$100.00"
                    display_total: "$100.00"
                    display_additional_tax_total: "$0.00"
                    display_included_tax_total: "$0.00"
                    display_tax_total: "$0.00"
                    delivery_method:
                      id: dm_UkLWZg9DAJ
                      name: UPS Ground
                      code: UPS_GROUND
                payments: []
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 187 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                shipping_address:
                  id: addr_VqXmZF31wY
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 188 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                payment_methods: []
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
        '422':
          description: discount code not found on cart
          content:
            application/json:
              example:
                error:
                  code: processing_error
                  message: The coupon code you entered doesn't exist. Please try again.
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/carts/{cart_id}/fulfillments/{id}":
    patch:
      summary: Select delivery rate for fulfillment
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Selects a delivery rate for a specific fulfillment and auto-advances
        checkout.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

          const cart = await client.carts.fulfillments.update('cart_abc123', 'ful_abc123', {
            selected_delivery_rate_id: 'dr_abc123',
          }, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Fulfillment ID
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        description: Order token for guest access
        schema:
          type: string
      responses:
        '200':
          description: delivery rate selected, returns updated cart
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R495333435
                token: vr5NsDydPesecXCDNmvqdhrE1FH96kV3K9s
                email: emil@abshiremayer.biz
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                item_total: '10.0'
                display_item_total: "$10.00"
                adjustment_total: '0.0'
                display_adjustment_total: "$0.00"
                discount_total: '0.0'
                display_discount_total: "$0.00"
                tax_total: '0.0'
                display_tax_total: "$0.00"
                included_tax_total: '0.0'
                display_included_tax_total: "$0.00"
                additional_tax_total: '0.0'
                display_additional_tax_total: "$0.00"
                total: '110.0'
                display_total: "$110.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '110.0'
                display_amount_due: "$110.00"
                delivery_total: '100.0'
                display_delivery_total: "$100.00"
                warnings: []
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                current_step: payment
                completed_steps:
                - address
                - delivery
                requirements:
                - step: payment
                  field: payment
                  message: Add a payment method
                shipping_eq_billing_address: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 1159495
                  slug: product-1159495
                  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: H32451339376
                  tracking: U10000
                  tracking_url:
                  cost: '100.0'
                  display_cost: "$100.00"
                  total: '100.0'
                  display_total: "$100.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  tax_total: '0.0'
                  display_tax_total: "$0.00"
                  status: pending
                  fulfillment_type: shipping
                  fulfilled_at:
                  items:
                  - item_id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                  delivery_method:
                    id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    code: UPS_GROUND
                  stock_location:
                    id: sloc_UkLWZg9DAJ
                    state_abbr: NY
                    name: Danika Wiza
                    address1: 1600 Pennsylvania Ave NW
                    city: Washington
                    zipcode: '20500'
                    country_iso: US
                    country_name: United States of America
                    state_text: NY
                  delivery_rates:
                  - id: dr_UkLWZg9DAJ
                    delivery_method_id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    selected: true
                    cost: '100.0'
                    total: '100.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    display_cost: "$100.00"
                    display_total: "$100.00"
                    display_additional_tax_total: "$0.00"
                    display_included_tax_total: "$0.00"
                    display_tax_total: "$0.00"
                    delivery_method:
                      id: dm_UkLWZg9DAJ
                      name: UPS Ground
                      code: UPS_GROUND
                payments: []
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 195 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                shipping_address:
                  id: addr_VqXmZF31wY
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 196 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                payment_methods: []
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
        '404':
          description: delivery rate not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Shipping rate not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                selected_delivery_rate_id:
                  type: string
                  example: dr_abc123
                  description: Delivery rate ID to select
              required:
              - selected_delivery_rate_id
  "/api/v3/store/carts/{cart_id}/gift_cards":
    post:
      summary: Apply gift card
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: |
        Applies a gift card to the cart. Gift cards are treated as a payment method, not a discount —
        the cart `total` remains unchanged while `amount_due` is reduced.

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

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

          const cart = await client.carts.giftCards.apply('cart_abc123', 'GC-ABCD-1234', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        description: Bearer token for authenticated customers
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        description: Order token for guest access
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID (e.g., cart_abc123)
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: Unique key for request idempotency.
        schema:
          type: string
      responses:
        '201':
          description: gift card applied
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R144554045
                token: RuTHka2EQdEPmHa7PXXzb8EAr5c9vSivWun
                email: claribel.funk@townekuhlman.us
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                item_total: '10.0'
                display_item_total: "$10.00"
                adjustment_total: '0.0'
                display_adjustment_total: "$0.00"
                discount_total: '0.0'
                display_discount_total: "$0.00"
                tax_total: '0.0'
                display_tax_total: "$0.00"
                included_tax_total: '0.0'
                display_included_tax_total: "$0.00"
                additional_tax_total: '0.0'
                display_additional_tax_total: "$0.00"
                total: '110.0'
                display_total: "$110.00"
                gift_card_total: '50.0'
                display_gift_card_total: "$50.00"
                amount_due: '60.0'
                display_amount_due: "$60.00"
                delivery_total: '100.0'
                display_delivery_total: "$100.00"
                warnings: []
                store_credit_total: '50.0'
                display_store_credit_total: "-$50.00"
                covered_by_store_credit: false
                current_step: address
                completed_steps: []
                requirements: []
                shipping_eq_billing_address: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 1174034
                  slug: product-1174034
                  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: H20393389861
                  tracking: U10000
                  tracking_url:
                  cost: '100.0'
                  display_cost: "$100.00"
                  total: '100.0'
                  display_total: "$100.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  tax_total: '0.0'
                  display_tax_total: "$0.00"
                  status: pending
                  fulfillment_type: shipping
                  fulfilled_at:
                  items:
                  - item_id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                  delivery_method:
                    id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    code: UPS_GROUND
                  stock_location:
                    id: sloc_UkLWZg9DAJ
                    state_abbr: NY
                    name: Gordon Pfeffer
                    address1: 1600 Pennsylvania Ave NW
                    city: Washington
                    zipcode: '20500'
                    country_iso: US
                    country_name: United States of America
                    state_text: NY
                  delivery_rates:
                  - id: dr_UkLWZg9DAJ
                    delivery_method_id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    selected: true
                    cost: '100.0'
                    total: '100.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    display_cost: "$100.00"
                    display_total: "$100.00"
                    display_additional_tax_total: "$0.00"
                    display_included_tax_total: "$0.00"
                    display_tax_total: "$0.00"
                    delivery_method:
                      id: dm_UkLWZg9DAJ
                      name: UPS Ground
                      code: UPS_GROUND
                payments:
                - id: py_UkLWZg9DAJ
                  payment_method_id: pm_UkLWZg9DAJ
                  response_code: 1-SC-20260526161400395109
                  number: PGO55NWN
                  amount: '50.0'
                  display_amount: "$50.00"
                  status: checkout
                  source_type: store_credit
                  source_id: credit_UkLWZg9DAJ
                  source:
                    id: credit_UkLWZg9DAJ
                    amount: '50.0'
                    amount_used: '0.0'
                    amount_remaining: '50.0'
                    display_amount: "$50.00"
                    display_amount_used: "$0.00"
                    display_amount_remaining: "$50.00"
                    currency: USD
                  payment_method:
                    id: pm_UkLWZg9DAJ
                    name: Store Credit
                    description:
                    type: store_credit
                    session_required: false
                    source_required: true
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 203 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                shipping_address:
                  id: addr_VqXmZF31wY
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 204 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                payment_methods:
                - id: pm_UkLWZg9DAJ
                  name: Store Credit
                  description:
                  type: store_credit
                  session_required: false
                  source_required: true
                gift_card:
                  id: gc_UkLWZg9DAJ
                  code: GIFTCODE1
                  status: active
                  currency: USD
                  amount: '50.0'
                  amount_used: '50.0'
                  amount_authorized: '0.0'
                  amount_remaining: '0.0'
                  display_amount: "$50.00"
                  display_amount_used: "$50.00"
                  display_amount_remaining: "$0.00"
                  expires_at:
                  redeemed_at:
                  expired: false
                  active: true
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
        '404':
          description: gift card not found
          content:
            application/json:
              example:
                error:
                  code: gift_card_not_found
                  message: The Gift Card was not found.
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '422':
          description: gift card already redeemed
          content:
            application/json:
              example:
                error:
                  code: gift_card_already_redeemed
                  message: The Gift Card has already been redeemed.
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                  example: GC-ABCD-1234
                  description: Gift card code to apply
              required:
              - code
  "/api/v3/store/carts/{cart_id}/gift_cards/{id}":
    delete:
      summary: Remove gift card
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Removes a previously applied gift card from the cart.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

          const cart = await client.carts.giftCards.remove('cart_abc123', 'gc_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        description: Bearer token for authenticated customers
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Gift card prefixed ID (e.g., gc_abc123)
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        description: Order token for guest access
        schema:
          type: string
      responses:
        '200':
          description: gift card removed
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R375402748
                token: zK6CyYENcBq5VLBnwSXE35w1RrR7o2sTgky
                email: tonita@klein.biz
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                item_total: '10.0'
                display_item_total: "$10.00"
                adjustment_total: '0.0'
                display_adjustment_total: "$0.00"
                discount_total: '0.0'
                display_discount_total: "$0.00"
                tax_total: '0.0'
                display_tax_total: "$0.00"
                included_tax_total: '0.0'
                display_included_tax_total: "$0.00"
                additional_tax_total: '0.0'
                display_additional_tax_total: "$0.00"
                total: '110.0'
                display_total: "$110.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '110.0'
                display_amount_due: "$110.00"
                delivery_total: '100.0'
                display_delivery_total: "$100.00"
                warnings: []
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                current_step: address
                completed_steps: []
                requirements:
                - step: payment
                  field: payment
                  message: Add a payment method
                shipping_eq_billing_address: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 1215119
                  slug: product-1215119
                  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: H49636801244
                  tracking: U10000
                  tracking_url:
                  cost: '100.0'
                  display_cost: "$100.00"
                  total: '100.0'
                  display_total: "$100.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  tax_total: '0.0'
                  display_tax_total: "$0.00"
                  status: pending
                  fulfillment_type: shipping
                  fulfilled_at:
                  items:
                  - item_id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                  delivery_method:
                    id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    code: UPS_GROUND
                  stock_location:
                    id: sloc_UkLWZg9DAJ
                    state_abbr: NY
                    name: Melvina Gottlieb
                    address1: 1600 Pennsylvania Ave NW
                    city: Washington
                    zipcode: '20500'
                    country_iso: US
                    country_name: United States of America
                    state_text: NY
                  delivery_rates:
                  - id: dr_UkLWZg9DAJ
                    delivery_method_id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    selected: true
                    cost: '100.0'
                    total: '100.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    display_cost: "$100.00"
                    display_total: "$100.00"
                    display_additional_tax_total: "$0.00"
                    display_included_tax_total: "$0.00"
                    display_tax_total: "$0.00"
                    delivery_method:
                      id: dm_UkLWZg9DAJ
                      name: UPS Ground
                      code: UPS_GROUND
                payments:
                - id: py_UkLWZg9DAJ
                  payment_method_id: pm_UkLWZg9DAJ
                  response_code: 1-SC-20260526161402955039
                  number: PIQFGKXI
                  amount: '50.0'
                  display_amount: "$50.00"
                  status: invalid
                  source_type: store_credit
                  source_id: credit_UkLWZg9DAJ
                  source:
                    id: credit_UkLWZg9DAJ
                    amount: '50.0'
                    amount_used: '0.0'
                    amount_remaining: '50.0'
                    display_amount: "$50.00"
                    display_amount_used: "$0.00"
                    display_amount_remaining: "$50.00"
                    currency: USD
                  payment_method:
                    id: pm_UkLWZg9DAJ
                    name: Store Credit
                    description:
                    type: store_credit
                    session_required: false
                    source_required: true
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 219 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                shipping_address:
                  id: addr_VqXmZF31wY
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 220 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                payment_methods: []
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
  "/api/v3/store/carts/{cart_id}/items":
    post:
      summary: Add item to cart
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Adds a variant to the cart. Creates a new line item or increases
        quantity if variant already in cart.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

          const cart = await client.carts.items.create('cart_abc123', {
            variant_id: 'variant_abc123',
            quantity: 2,
          }, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        description: Bearer token for authenticated customers
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        description: Order token for guest access
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID (e.g., cart_abc123)
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: Unique key for request idempotency.
        schema:
          type: string
      responses:
        '201':
          description: item added with metadata
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R128024977
                token: snfWbJhSsShSGdMgtj6NVNbk7SVZvg984Xb
                email: danica.trantow@mcglynndicki.name
                customer_note:
                currency: USD
                locale: en
                total_quantity: 2
                item_total: '29.99'
                display_item_total: "$29.99"
                adjustment_total: '0.0'
                display_adjustment_total: "$0.00"
                discount_total: '0.0'
                display_discount_total: "$0.00"
                tax_total: '0.0'
                display_tax_total: "$0.00"
                included_tax_total: '0.0'
                display_included_tax_total: "$0.00"
                additional_tax_total: '0.0'
                display_additional_tax_total: "$0.00"
                total: '29.99'
                display_total: "$29.99"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '29.99'
                display_amount_due: "$29.99"
                delivery_total: '0.0'
                display_delivery_total: "$0.00"
                warnings: []
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                current_step: address
                completed_steps: []
                requirements:
                - step: address
                  field: ship_address
                  message: Shipping address is required
                - step: delivery
                  field: shipping_method
                  message: Select a shipping method for all shipments
                - step: payment
                  field: payment
                  message: Add a payment method
                shipping_eq_billing_address: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 1244584
                  slug: product-1244584
                  options_text: ''
                  price: '10.0'
                  display_price: "$10.00"
                  total: '10.0'
                  display_total: "$10.00"
                  adjustment_total: '0.0'
                  display_adjustment_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  pre_tax_amount: '10.0'
                  display_pre_tax_amount: "$10.00"
                  discounted_amount: '10.0'
                  display_discounted_amount: "$10.00"
                  display_compare_at_amount: "$0.00"
                  compare_at_amount:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                - id: li_gbHJdmfrXB
                  variant_id: variant_gbHJdmfrXB
                  quantity: 1
                  currency: USD
                  name: Product 1253628
                  slug: product-1253628
                  options_text: ''
                  price: '19.99'
                  display_price: "$19.99"
                  total: '19.99'
                  display_total: "$19.99"
                  adjustment_total: '0.0'
                  display_adjustment_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  pre_tax_amount: '19.99'
                  display_pre_tax_amount: "$19.99"
                  discounted_amount: '19.99'
                  display_discounted_amount: "$19.99"
                  display_compare_at_amount: "$0.00"
                  compare_at_amount:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments: []
                payments: []
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 234 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                shipping_address:
                payment_methods: []
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
        '404':
          description: variant not found
          content:
            application/json:
              example:
                error:
                  code: variant_not_found
                  message: Variant not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                variant_id:
                  type: string
                  example: variant_abc123
                  description: Variant ID to add
                quantity:
                  type: integer
                  example: 2
                  description: 'Quantity to add (default: 1)'
                metadata:
                  type: object
                  additionalProperties: true
                  description: Arbitrary key-value metadata
                  example:
                    gift_message: Happy Birthday!
              required:
              - variant_id
  "/api/v3/store/carts/{cart_id}/items/{id}":
    patch:
      summary: Update line item quantity
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Updates the quantity of a line item in the cart
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

          const cart = await client.carts.items.update('cart_abc123', 'li_abc123', {
            quantity: 5,
          }, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Line item ID
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: metadata updated on line item
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R216067679
                token: HBo9TtU6Kra7Pkqey8Rhw5WW93WSsLFKbcb
                email: lowell@lakin.co.uk
                customer_note:
                currency: USD
                locale: en
                total_quantity: 0
                item_total: '0.0'
                display_item_total: "$0.00"
                adjustment_total: '0.0'
                display_adjustment_total: "$0.00"
                discount_total: '0.0'
                display_discount_total: "$0.00"
                tax_total: '0.0'
                display_tax_total: "$0.00"
                included_tax_total: '0.0'
                display_included_tax_total: "$0.00"
                additional_tax_total: '0.0'
                display_additional_tax_total: "$0.00"
                total: '0.0'
                display_total: "$0.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '0.0'
                display_amount_due: "$0.00"
                delivery_total: '0.0'
                display_delivery_total: "$0.00"
                warnings: []
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                current_step: address
                completed_steps: []
                requirements:
                - step: address
                  field: ship_address
                  message: Shipping address is required
                - step: delivery
                  field: shipping_method
                  message: Select a shipping method for all shipments
                shipping_eq_billing_address: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 1289337
                  slug: product-1289337
                  options_text: ''
                  price: '10.0'
                  display_price: "$10.00"
                  total: '10.0'
                  display_total: "$10.00"
                  adjustment_total: '0.0'
                  display_adjustment_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  pre_tax_amount: '10.0'
                  display_pre_tax_amount: "$10.00"
                  discounted_amount: '10.0'
                  display_discounted_amount: "$10.00"
                  display_compare_at_amount: "$0.00"
                  compare_at_amount:
                  thumbnail_url:
                  option_values: []
                  digital_links: []
                fulfillments: []
                payments: []
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 243 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                shipping_address:
                payment_methods: []
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                quantity:
                  type: integer
                  minimum: 1
                  example: 5
                metadata:
                  type: object
                  additionalProperties: true
                  description: Arbitrary key-value metadata (merged with existing)
                  example:
                    engraving: J.D.
    delete:
      summary: Remove line item from cart
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Removes a line item from the cart
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

          const cart = await client.carts.items.delete('cart_abc123', 'li_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: line item removed, returns updated cart
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R262930205
                token: 6F91AsEuASghgSqqpwTgtCCF84SEMYm1ozP
                email: gwenn_hessel@auerreilly.ca
                customer_note:
                currency: USD
                locale: en
                total_quantity: 0
                item_total: '0.0'
                display_item_total: "$0.00"
                adjustment_total: '0.0'
                display_adjustment_total: "$0.00"
                discount_total: '0.0'
                display_discount_total: "$0.00"
                tax_total: '0.0'
                display_tax_total: "$0.00"
                included_tax_total: '0.0'
                display_included_tax_total: "$0.00"
                additional_tax_total: '0.0'
                display_additional_tax_total: "$0.00"
                total: '0.0'
                display_total: "$0.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '0.0'
                display_amount_due: "$0.00"
                delivery_total: '0.0'
                display_delivery_total: "$0.00"
                warnings: []
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                current_step: address
                completed_steps: []
                requirements:
                - step: cart
                  field: line_items
                  message: Add at least one item to your cart
                - step: address
                  field: ship_address
                  message: Shipping address is required
                - step: delivery
                  field: shipping_method
                  message: Select a shipping method for all shipments
                shipping_eq_billing_address: false
                discounts: []
                items: []
                fulfillments: []
                payments: []
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 246 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                shipping_address:
                payment_methods: []
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
        '404':
          description: line item not found
          content:
            application/json:
              example:
                error:
                  code: line_item_not_found
                  message: Line item not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/carts/{cart_id}/payment_sessions":
    post:
      summary: Create payment session
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Creates a new payment session for the cart. Delegates to the payment
        gateway to initialize a provider-specific session (e.g. Stripe PaymentIntent,
        Adyen session, PayPal order).
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

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

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

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

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

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

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

          const session = await client.carts.paymentSessions.complete('cart_abc123', 'ps_abc123', {
            session_result: 'success',
          }, {
            token: '<token>',
          })
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Unique key for request idempotency.
        schema:
          type: string
      responses:
        '200':
          description: payment session completed
          content:
            application/json:
              example:
                id: ps_UkLWZg9DAJ
                status: completed
                currency: USD
                external_id: bogus_2ebf387c2f1e00f23440c181
                external_data:
                  client_secret: secret_123
                customer_external_id:
                expires_at:
                amount: '110.0'
                payment_method_id: pm_UkLWZg9DAJ
                order_id: or_UkLWZg9DAJ
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Credit Card
                  description:
                  type: bogus
                  session_required: true
                  source_required: true
              schema:
                "$ref": "#/components/schemas/PaymentSession"
        '404':
          description: payment session not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Payment session not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                session_result:
                  type: string
                  description: Provider-specific session result token
                external_data:
                  type: object
                  description: Provider-specific completion data
  "/api/v3/store/carts/{cart_id}/payments":
    post:
      summary: Create payment
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Creates a payment for a non-session payment method (e.g. Check,
        Cash on Delivery, Bank Transfer). For payment methods that require a session
        (e.g. Stripe, PayPal), use the payment sessions endpoint instead.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

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

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

          const cart = await client.carts.storeCredits.apply('cart_abc123', 10.0, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID (e.g., cart_abc123)
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: Unique key for request idempotency.
        schema:
          type: string
      responses:
        '200':
          description: store credit applied
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R903776007
                token: oPFUDLqngFUNHBsLi5NZyBfVqQFVkab5S48
                email: despina.ernser@leffler.us
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                item_total: '10.0'
                display_item_total: "$10.00"
                adjustment_total: '0.0'
                display_adjustment_total: "$0.00"
                discount_total: '0.0'
                display_discount_total: "$0.00"
                tax_total: '0.0'
                display_tax_total: "$0.00"
                included_tax_total: '0.0'
                display_included_tax_total: "$0.00"
                additional_tax_total: '0.0'
                display_additional_tax_total: "$0.00"
                total: '110.0'
                display_total: "$110.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '100.0'
                display_amount_due: "$100.00"
                delivery_total: '100.0'
                display_delivery_total: "$100.00"
                warnings: []
                store_credit_total: '10.0'
                display_store_credit_total: "-$10.00"
                covered_by_store_credit: false
                current_step: address
                completed_steps: []
                requirements: []
                shipping_eq_billing_address: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 1909153
                  slug: product-1909153
                  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: H71098380344
                  tracking: U10000
                  tracking_url:
                  cost: '100.0'
                  display_cost: "$100.00"
                  total: '100.0'
                  display_total: "$100.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  tax_total: '0.0'
                  display_tax_total: "$0.00"
                  status: pending
                  fulfillment_type: shipping
                  fulfilled_at:
                  items:
                  - item_id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                  delivery_method:
                    id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    code: UPS_GROUND
                  stock_location:
                    id: sloc_UkLWZg9DAJ
                    state_abbr: NY
                    name: Twanna Stamm
                    address1: 1600 Pennsylvania Ave NW
                    city: Washington
                    zipcode: '20500'
                    country_iso: US
                    country_name: United States of America
                    state_text: NY
                  delivery_rates:
                  - id: dr_UkLWZg9DAJ
                    delivery_method_id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    selected: true
                    cost: '100.0'
                    total: '100.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    display_cost: "$100.00"
                    display_total: "$100.00"
                    display_additional_tax_total: "$0.00"
                    display_included_tax_total: "$0.00"
                    display_tax_total: "$0.00"
                    delivery_method:
                      id: dm_UkLWZg9DAJ
                      name: UPS Ground
                      code: UPS_GROUND
                payments:
                - id: py_UkLWZg9DAJ
                  payment_method_id: pm_UkLWZg9DAJ
                  response_code: 1-SC-20260526161430523363
                  number: P1X82P2A
                  amount: '10.0'
                  display_amount: "$10.00"
                  status: checkout
                  source_type: store_credit
                  source_id: credit_UkLWZg9DAJ
                  source:
                    id: credit_UkLWZg9DAJ
                    amount: '50.0'
                    amount_used: '0.0'
                    amount_remaining: '50.0'
                    display_amount: "$50.00"
                    display_amount_used: "$0.00"
                    display_amount_remaining: "$50.00"
                    currency: USD
                  payment_method:
                    id: pm_UkLWZg9DAJ
                    name: Store Credit
                    description: Store Credit
                    type: store_credit
                    session_required: false
                    source_required: true
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 320 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                shipping_address:
                  id: addr_VqXmZF31wY
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 321 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                payment_methods:
                - id: pm_UkLWZg9DAJ
                  name: Store Credit
                  description: Store Credit
                  type: store_credit
                  session_required: false
                  source_required: true
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
        '422':
          description: no store credit available
          content:
            application/json:
              example:
                error:
                  code: processing_error
                  message: User does not have any Store Credits available
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  example: 10.0
                  description: Amount to apply (optional - defaults to max available)
    delete:
      summary: Remove store credit
      tags:
      - Carts
      security:
      - api_key: []
        bearer_auth: []
      description: Removes store credit from the cart.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

          const cart = await client.carts.storeCredits.remove('cart_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: store credit removed
          content:
            application/json:
              example:
                id: cart_UkLWZg9DAJ
                market_id:
                number: R646602683
                token: c5RmvpB42n2ZRwYZ246jBJSFzvFgSLjsY5V
                email: kristle@vandervort.biz
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                item_total: '10.0'
                display_item_total: "$10.00"
                adjustment_total: '0.0'
                display_adjustment_total: "$0.00"
                discount_total: '0.0'
                display_discount_total: "$0.00"
                tax_total: '0.0'
                display_tax_total: "$0.00"
                included_tax_total: '0.0'
                display_included_tax_total: "$0.00"
                additional_tax_total: '0.0'
                display_additional_tax_total: "$0.00"
                total: '110.0'
                display_total: "$110.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '110.0'
                display_amount_due: "$110.00"
                delivery_total: '100.0'
                display_delivery_total: "$100.00"
                warnings: []
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                current_step: address
                completed_steps: []
                requirements:
                - step: payment
                  field: payment
                  message: Add a payment method
                shipping_eq_billing_address: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 1922421
                  slug: product-1922421
                  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: H93482247486
                  tracking: U10000
                  tracking_url:
                  cost: '100.0'
                  display_cost: "$100.00"
                  total: '100.0'
                  display_total: "$100.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  tax_total: '0.0'
                  display_tax_total: "$0.00"
                  status: pending
                  fulfillment_type: shipping
                  fulfilled_at:
                  items:
                  - item_id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                  delivery_method:
                    id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    code: UPS_GROUND
                  stock_location:
                    id: sloc_UkLWZg9DAJ
                    state_abbr: NY
                    name: Carolina Kovacek
                    address1: 1600 Pennsylvania Ave NW
                    city: Washington
                    zipcode: '20500'
                    country_iso: US
                    country_name: United States of America
                    state_text: NY
                  delivery_rates:
                  - id: dr_UkLWZg9DAJ
                    delivery_method_id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    selected: true
                    cost: '100.0'
                    total: '100.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    display_cost: "$100.00"
                    display_total: "$100.00"
                    display_additional_tax_total: "$0.00"
                    display_included_tax_total: "$0.00"
                    display_tax_total: "$0.00"
                    delivery_method:
                      id: dm_UkLWZg9DAJ
                      name: UPS Ground
                      code: UPS_GROUND
                payments: []
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 328 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                shipping_address:
                  id: addr_VqXmZF31wY
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 329 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                payment_methods: []
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Cart"
  "/api/v3/store/orders/{id}":
    get:
      summary: Get an order
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: Returns a single completed order by prefixed ID. Accessible via
        JWT (authenticated users) or order token header (guests).
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

          const order = await client.orders.get('or_abc123', {}, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        description: Bearer token for authenticated customers
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: x-spree-token
        in: header
        required: false
        description: Order token for guest access
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (items, fulfillments,
          payments, discounts, billing_address, shipping_address, gift_card). Use
          "none" to skip associations.
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., total,amount_due,item_count).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: order found (guest via order token)
          content:
            application/json:
              example:
                id: or_UkLWZg9DAJ
                market_id:
                channel_id: ch_UkLWZg9DAJ
                number: R528526445
                email: guest@example.com
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                item_total: '10.0'
                display_item_total: "$10.00"
                adjustment_total: '0.0'
                display_adjustment_total: "$0.00"
                discount_total: '0.0'
                display_discount_total: "$0.00"
                tax_total: '0.0'
                display_tax_total: "$0.00"
                included_tax_total: '0.0'
                display_included_tax_total: "$0.00"
                additional_tax_total: '0.0'
                display_additional_tax_total: "$0.00"
                total: '110.0'
                display_total: "$110.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '110.0'
                display_amount_due: "$110.00"
                delivery_total: '100.0'
                display_delivery_total: "$100.00"
                fulfillment_status:
                payment_status:
                completed_at: '2026-05-26T16:14:12.058Z'
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 1325879
                  slug: product-1325879
                  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: H26728427796
                  tracking: U10000
                  tracking_url:
                  cost: '100.0'
                  display_cost: "$100.00"
                  total: '100.0'
                  display_total: "$100.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  tax_total: '0.0'
                  display_tax_total: "$0.00"
                  status: pending
                  fulfillment_type: shipping
                  fulfilled_at:
                  items:
                  - item_id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                  delivery_method:
                    id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    code: UPS_GROUND
                  stock_location:
                    id: sloc_UkLWZg9DAJ
                    state_abbr: NY
                    name: Maida Rogahn
                    address1: 1600 Pennsylvania Ave NW
                    city: Washington
                    zipcode: '20500'
                    country_iso: US
                    country_name: United States of America
                    state_text: NY
                  delivery_rates:
                  - id: dr_gbHJdmfrXB
                    delivery_method_id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    selected: true
                    cost: '10.0'
                    total: '10.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    display_cost: "$10.00"
                    display_total: "$10.00"
                    display_additional_tax_total: "$0.00"
                    display_included_tax_total: "$0.00"
                    display_tax_total: "$0.00"
                    delivery_method:
                      id: dm_UkLWZg9DAJ
                      name: UPS Ground
                      code: UPS_GROUND
                payments: []
                billing_address:
                  id: addr_UkLWZg9DAJ
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 256 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                shipping_address:
                  id: addr_gbHJdmfrXB
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 257 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Order"
        '404':
          description: incomplete order not accessible
          content:
            application/json:
              example:
                error:
                  code: order_not_found
                  message: Order not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/customers/me/addresses":
    get:
      summary: List customer addresses
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Returns all addresses in the customer address book
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

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

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

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

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

          const address = await client.customer.addresses.get('addr_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: address found
          content:
            application/json:
              example:
                id: addr_EfhxLZ9ck8
                first_name: John
                last_name: Doe
                full_name: John Doe
                address1: 84 Lovely Street
                address2: Northwest
                postal_code: '10118'
                city: New York
                phone: 555-555-0199
                company: Company
                country_name: United States of America
                country_iso: US
                state_text: NY
                state_abbr: NY
                quick_checkout: false
                is_default_billing: false
                is_default_shipping: false
                state_name: New York
              schema:
                "$ref": "#/components/schemas/Address"
        '404':
          description: address not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Address not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update an address
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

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

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

          await client.customer.addresses.delete('addr_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: address deleted
        '404':
          description: address not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Address not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/customers/me/credit_cards":
    get:
      summary: List saved credit cards
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Returns all saved credit cards for the authenticated customer
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

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

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

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

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

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

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

          const orders = await client.customer.orders.list(
            {
              completed_at_gt: '2026-01-01',
              sort: '-completed_at',
            },
            { token: '<token>' },
          )
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: 'Page number (default: 1)'
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: 'Number of results per page (default: 25, max: 100)'
        schema:
          type: integer
      - name: sort
        in: query
        required: false
        description: 'Sort order. Prefix with - for descending. Values: completed_at,
          -completed_at, total, -total, number, -number'
        schema:
          type: string
      - name: q[completed_at_gt]
        in: query
        required: false
        description: Filter by completed after date (ISO 8601)
        schema:
          type: string
      - name: q[completed_at_lt]
        in: query
        required: false
        description: Filter by completed before date (ISO 8601)
        schema:
          type: string
      - name: q[number_eq]
        in: query
        required: false
        description: Filter by exact order number (e.g., R123456)
        schema:
          type: string
      - name: q[state_eq]
        in: query
        required: false
        description: Filter by order state (complete, returned, canceled)
        schema:
          type: string
      - name: q[payment_state_eq]
        in: query
        required: false
        description: Filter by payment state (paid, balance_due, credit_owed, void,
          failed)
        schema:
          type: string
      - name: q[total_gteq]
        in: query
        required: false
        description: Filter by minimum total
        schema:
          type: number
      - name: q[total_lteq]
        in: query
        required: false
        description: Filter by maximum total
        schema:
          type: number
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (items, fulfillments,
          payments, discounts, billing_address, shipping_address, gift_card). Use
          "none" to skip associations.
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., total,amount_due,item_count).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: orders listed
          content:
            application/json:
              example:
                data:
                - id: or_UkLWZg9DAJ
                  market_id:
                  channel_id: ch_UkLWZg9DAJ
                  number: R096824993
                  email: gena@ohara.biz
                  customer_note:
                  currency: USD
                  locale: en
                  total_quantity: 1
                  item_total: '10.0'
                  display_item_total: "$10.00"
                  adjustment_total: '0.0'
                  display_adjustment_total: "$0.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  tax_total: '0.0'
                  display_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  total: '110.0'
                  display_total: "$110.00"
                  gift_card_total: '0.0'
                  display_gift_card_total: "$0.00"
                  amount_due: '110.0'
                  display_amount_due: "$110.00"
                  delivery_total: '100.0'
                  display_delivery_total: "$100.00"
                  fulfillment_status:
                  payment_status:
                  completed_at: '2026-05-26T16:13:49.079Z'
                  store_credit_total: '0.0'
                  display_store_credit_total: "$0.00"
                  covered_by_store_credit: false
                  discounts: []
                  items:
                  - id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                    currency: USD
                    name: Product 1016128
                    slug: product-1016128
                    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: H70742962050
                    tracking: U10000
                    tracking_url:
                    cost: '100.0'
                    display_cost: "$100.00"
                    total: '100.0'
                    display_total: "$100.00"
                    discount_total: '0.0'
                    display_discount_total: "$0.00"
                    additional_tax_total: '0.0'
                    display_additional_tax_total: "$0.00"
                    included_tax_total: '0.0'
                    display_included_tax_total: "$0.00"
                    tax_total: '0.0'
                    display_tax_total: "$0.00"
                    status: pending
                    fulfillment_type: shipping
                    fulfilled_at:
                    items:
                    - item_id: li_UkLWZg9DAJ
                      variant_id: variant_UkLWZg9DAJ
                      quantity: 1
                    delivery_method:
                      id: dm_UkLWZg9DAJ
                      name: UPS Ground
                      code: UPS_GROUND
                    stock_location:
                      id: sloc_UkLWZg9DAJ
                      state_abbr: NY
                      name: Britany Halvorson
                      address1: 1600 Pennsylvania Ave NW
                      city: Washington
                      zipcode: '20500'
                      country_iso: US
                      country_name: United States of America
                      state_text: NY
                    delivery_rates:
                    - id: dr_gbHJdmfrXB
                      delivery_method_id: dm_UkLWZg9DAJ
                      name: UPS Ground
                      selected: true
                      cost: '10.0'
                      total: '10.0'
                      additional_tax_total: '0.0'
                      included_tax_total: '0.0'
                      tax_total: '0.0'
                      display_cost: "$10.00"
                      display_total: "$10.00"
                      display_additional_tax_total: "$0.00"
                      display_included_tax_total: "$0.00"
                      display_tax_total: "$0.00"
                      delivery_method:
                        id: dm_UkLWZg9DAJ
                        name: UPS Ground
                        code: UPS_GROUND
                  payments: []
                  billing_address:
                    id: addr_EfhxLZ9ck8
                    first_name: John
                    last_name: Doe
                    full_name: John Doe
                    address1: 147 Lovely Street
                    address2: Northwest
                    postal_code: '10118'
                    city: New York
                    phone: 555-555-0199
                    company: Company
                    country_name: United States of America
                    country_iso: US
                    state_text: NY
                    state_abbr: NY
                    quick_checkout: false
                    is_default_billing: false
                    is_default_shipping: false
                    state_name: New York
                  shipping_address:
                    id: addr_VqXmZF31wY
                    first_name: John
                    last_name: Doe
                    full_name: John Doe
                    address1: 148 Lovely Street
                    address2: Northwest
                    postal_code: '10118'
                    city: New York
                    phone: 555-555-0199
                    company: Company
                    country_name: United States of America
                    country_iso: US
                    state_text: NY
                    state_abbr: NY
                    quick_checkout: false
                    is_default_billing: false
                    is_default_shipping: false
                    state_name: New York
                  gift_card:
                  market:
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Order"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/customers/me/orders/{id}":
    get:
      summary: Get an order
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Returns a single completed order for the authenticated customer.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

          const order = await client.customer.orders.get('or_abc123', {}, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (items, fulfillments,
          payments, discounts, billing_address, shipping_address, gift_card). Use
          "none" to skip associations.
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., total,amount_due,item_count).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: order found
          content:
            application/json:
              example:
                id: or_UkLWZg9DAJ
                market_id:
                channel_id: ch_UkLWZg9DAJ
                number: R695830260
                email: jerica.wehner@wintheiser.biz
                customer_note:
                currency: USD
                locale: en
                total_quantity: 1
                item_total: '10.0'
                display_item_total: "$10.00"
                adjustment_total: '0.0'
                display_adjustment_total: "$0.00"
                discount_total: '0.0'
                display_discount_total: "$0.00"
                tax_total: '0.0'
                display_tax_total: "$0.00"
                included_tax_total: '0.0'
                display_included_tax_total: "$0.00"
                additional_tax_total: '0.0'
                display_additional_tax_total: "$0.00"
                total: '110.0'
                display_total: "$110.00"
                gift_card_total: '0.0'
                display_gift_card_total: "$0.00"
                amount_due: '110.0'
                display_amount_due: "$110.00"
                delivery_total: '100.0'
                display_delivery_total: "$100.00"
                fulfillment_status:
                payment_status:
                completed_at: '2026-05-26T16:13:49.771Z'
                store_credit_total: '0.0'
                display_store_credit_total: "$0.00"
                covered_by_store_credit: false
                discounts: []
                items:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                  currency: USD
                  name: Product 1033099
                  slug: product-1033099
                  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: H08221240082
                  tracking: U10000
                  tracking_url:
                  cost: '100.0'
                  display_cost: "$100.00"
                  total: '100.0'
                  display_total: "$100.00"
                  discount_total: '0.0'
                  display_discount_total: "$0.00"
                  additional_tax_total: '0.0'
                  display_additional_tax_total: "$0.00"
                  included_tax_total: '0.0'
                  display_included_tax_total: "$0.00"
                  tax_total: '0.0'
                  display_tax_total: "$0.00"
                  status: pending
                  fulfillment_type: shipping
                  fulfilled_at:
                  items:
                  - item_id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                  delivery_method:
                    id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    code: UPS_GROUND
                  stock_location:
                    id: sloc_UkLWZg9DAJ
                    state_abbr: NY
                    name: Aleen Reynolds
                    address1: 1600 Pennsylvania Ave NW
                    city: Washington
                    zipcode: '20500'
                    country_iso: US
                    country_name: United States of America
                    state_text: NY
                  delivery_rates:
                  - id: dr_gbHJdmfrXB
                    delivery_method_id: dm_UkLWZg9DAJ
                    name: UPS Ground
                    selected: true
                    cost: '10.0'
                    total: '10.0'
                    additional_tax_total: '0.0'
                    included_tax_total: '0.0'
                    tax_total: '0.0'
                    display_cost: "$10.00"
                    display_total: "$10.00"
                    display_additional_tax_total: "$0.00"
                    display_included_tax_total: "$0.00"
                    display_tax_total: "$0.00"
                    delivery_method:
                      id: dm_UkLWZg9DAJ
                      name: UPS Ground
                      code: UPS_GROUND
                payments: []
                billing_address:
                  id: addr_EfhxLZ9ck8
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 153 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                shipping_address:
                  id: addr_VqXmZF31wY
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 154 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                gift_card:
                market:
              schema:
                "$ref": "#/components/schemas/Order"
        '404':
          description: order belongs to another user
          content:
            application/json:
              example:
                error:
                  code: order_not_found
                  message: Order not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/customers":
    post:
      summary: Register a new customer
      tags:
      - Customers
      security:
      - api_key: []
      description: Creates a new customer account and returns a JWT token
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

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

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

          const customer = await client.customer.get({
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer JWT token
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: profile found
          content:
            application/json:
              example:
                id: cus_UkLWZg9DAJ
                email: jama.wolff@lynch.biz
                first_name: Catarina
                last_name: Padberg
                phone: 555-555-0199
                accepts_email_marketing: false
                full_name: Catarina Padberg
                available_store_credit_total: '0'
                display_available_store_credit_total: "$0.00"
                addresses:
                - id: addr_gbHJdmfrXB
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 160 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: true
                  is_default_shipping: false
                  state_name: New York
                - id: addr_UkLWZg9DAJ
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 159 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: true
                  state_name: New York
                default_billing_address:
                  id: addr_gbHJdmfrXB
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 160 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: true
                  is_default_shipping: false
                  state_name: New York
                default_shipping_address:
                  id: addr_UkLWZg9DAJ
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 159 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: true
                  state_name: New York
              schema:
                "$ref": "#/components/schemas/Customer"
        '401':
          description: unauthorized - invalid token
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update current customer profile
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Updates the profile of the currently authenticated customer
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

          const customer = await client.customer.update({
            first_name: 'John',
            last_name: 'Doe',
            metadata: { preferred_contact: 'email' },
          }, {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: profile updated
          content:
            application/json:
              example:
                id: cus_UkLWZg9DAJ
                email: kiera@treutel.com
                first_name: Updated
                last_name: Name
                phone: 555-555-0199
                accepts_email_marketing: false
                full_name: Updated Name
                available_store_credit_total: '0'
                display_available_store_credit_total: "$0.00"
                addresses:
                - id: addr_gbHJdmfrXB
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 162 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: true
                  is_default_shipping: false
                  state_name: New York
                - id: addr_UkLWZg9DAJ
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 161 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: true
                  state_name: New York
                default_billing_address:
                  id: addr_gbHJdmfrXB
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 162 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: true
                  is_default_shipping: false
                  state_name: New York
                default_shipping_address:
                  id: addr_UkLWZg9DAJ
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 161 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States of America
                  country_iso: US
                  state_text: NY
                  state_abbr: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: true
                  state_name: New York
              schema:
                "$ref": "#/components/schemas/Customer"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Email can't be blank
                  details:
                    email:
                    - can't be blank
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                  example: John
                last_name:
                  type: string
                  example: Doe
                email:
                  type: string
                  format: email
                  example: customer@example.com
                password:
                  type: string
                  example: newpassword123
                password_confirmation:
                  type: string
                  example: newpassword123
                accepts_email_marketing:
                  type: boolean
                  example: true
                phone:
                  type: string
                  example: "+1 555 123 4567"
                metadata:
                  type: object
                  example:
                    preferred_contact: email
  "/api/v3/store/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: 91F1E57C6C99A62C
                  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: 76D77B6CFFA255C8
                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_e60689fe4c66251e2b4dd2f4
                external_client_secret: bogus_seti_secret_633045dc9ddab700
                external_data: {}
                payment_method_id: pm_UkLWZg9DAJ
                payment_source_id:
                payment_source_type:
                customer_id: cus_UkLWZg9DAJ
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Credit Card
                  description:
                  type: bogus
                  session_required: true
                  source_required: true
              schema:
                "$ref": "#/components/schemas/PaymentSetupSession"
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '404':
          description: payment method not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Payment method not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                payment_method_id:
                  type: string
                  example: pm_abc123
                  description: Payment method ID
                external_data:
                  type: object
                  description: Provider-specific data passed to the gateway
              required:
              - payment_method_id
  "/api/v3/store/customers/me/payment_setup_sessions/{id}":
    parameters:
    - name: x-spree-api-key
      in: header
      required: true
      schema:
        type: string
    - name: Authorization
      in: header
      required: true
      schema:
        type: string
    - name: id
      in: path
      required: true
      description: Payment setup session ID
      schema:
        type: string
    get:
      summary: Get payment setup session
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Returns a payment setup session with its current status and provider
        data.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

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

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

          const session = await client.customer.paymentSetupSessions.complete('pss_abc123', {}, {
            token: '<token>',
          })
      parameters: []
      responses:
        '200':
          description: payment setup session completed
          content:
            application/json:
              example:
                id: pss_UkLWZg9DAJ
                status: completed
                external_id: seti_test_6cb96d4ae6cdc1eadf02b1dc
                external_client_secret: seti_secret_bb0a7727be4c699d8584292f
                external_data:
                  client_secret: secret_123
                payment_method_id: pm_UkLWZg9DAJ
                payment_source_id: card_UkLWZg9DAJ
                payment_source_type: Spree::CreditCard
                customer_id: cus_UkLWZg9DAJ
                payment_method:
                  id: pm_UkLWZg9DAJ
                  name: Credit Card
                  description:
                  type: bogus
                  session_required: true
                  source_required: true
              schema:
                "$ref": "#/components/schemas/PaymentSetupSession"
        '404':
          description: payment setup session not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Payment setup session not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                external_data:
                  type: object
                  description: Provider-specific completion data
  "/api/v3/store/customers/me/store_credits":
    get:
      summary: List store credits
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: Returns store credits for the authenticated customer, filtered
        by current store and currency. Supports Ransack filtering.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

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

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

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

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

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

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

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

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

          const currencies = await client.currencies.list()
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: currencies found
          content:
            application/json:
              example:
                data:
                - iso_code: USD
                  name: United States Dollar
                  symbol: "$"
                - iso_code: EUR
                  name: Euro
                  symbol: "€"
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Currency"
                required:
                - data
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: Valid API key required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/locales":
    get:
      summary: List supported locales
      tags:
      - Markets
      security:
      - api_key: []
      description: Returns locales supported by the store (derived from markets)
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

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

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

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

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

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

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

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

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

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

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

          const country = await client.markets.countries.get('mkt_xxx', 'DE')
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: market_id
        in: path
        required: true
        description: Market prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Country ISO 3166-1 alpha-2 code (e.g., "DE")
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: country found
          content:
            application/json:
              example:
                iso: US
                iso3: USA
                name: United States of America
                states_required: true
                zipcode_required: true
              schema:
                type: object
        '404':
          description: country not in market
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Country not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/store/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: KrDYvpcWeMWWCVsEuRj9V8Xm
                  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: LoTGXDT4V69PBMZXRWaS9Sjg
                is_default: false
                is_private: true
              schema:
                "$ref": "#/components/schemas/Wishlist"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Name can't be blank
                  details:
                    name:
                    - can't be blank
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Birthday Ideas
                is_private:
                  type: boolean
                  example: true
                is_default:
                  type: boolean
                  example: false
              required:
              - name
  "/api/v3/store/wishlists/{id}":
    get:
      summary: Get a wishlist
      tags:
      - Wishlists
      security:
      - api_key: []
        bearer_auth: []
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

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

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

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

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

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

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

          await client.wishlists.items.delete('wl_abc123', 'wi_abc123', {
            token: '<token>',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: wishlist_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: item removed
        '404':
          description: item not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Wished item not found
  "/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: harriet.conroy@mohr.co.uk
                created_at: '2026-05-26T16:14:11.183Z'
                updated_at: '2026-05-26T16:14:11.186Z'
                verified: true
                verified_at: '2026-05-26T16:14:11Z'
                customer_id: cus_UkLWZg9DAJ
              schema:
                "$ref": "#/components/schemas/NewsletterSubscriber"
        '422':
          description: invalid email format
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Email is invalid
                  details:
                    email:
                    - is invalid
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  example: subscriber@example.com
                redirect_url:
                  type: string
                  format: uri
                  example: https://your-store.com/newsletter/confirm
                  description: Storefront URL the verification token should be appended
                    to. Silently omitted from the webhook payload when the store has
                    allowed origins configured and this URL does not match one of
                    them, or when no allowed origins are configured at all.
              required:
              - email
  "/api/v3/store/newsletter_subscribers/verify":
    post:
      summary: Verify a newsletter subscription
      tags:
      - Newsletter Subscribers
      security:
      - api_key: []
      description: |
        Confirms a pending newsletter subscription using the verification token sent by email.

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

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

          const subscriber = await client.newsletterSubscribers.verify({
            token: 'abc123def456',
          })
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: subscription verified
          content:
            application/json:
              example:
                id: sub_UkLWZg9DAJ
                email: pending@example.com
                created_at: '2026-05-26T16:14:11.236Z'
                updated_at: '2026-05-26T16:14:11.255Z'
                verified: true
                verified_at: '2026-05-26T16:14:11Z'
                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/policies":
    get:
      summary: List store policies
      tags:
      - Policies
      security:
      - api_key: []
      description: |
        Returns all policies for the current store (e.g., return policy, privacy policy, terms of service).
        Policies are managed in Spree Admin and contain rich text content.
      x-codeSamples:
      - lang: javascript
        label: Spree SDK
        source: |-
          import { createClient } from '@spree/sdk'

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

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

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

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