Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

2.7 MB
Raw Blame
---
openapi: 3.0.3
info:
  title: Admin API
  contact:
    name: Spree Commerce
    url: https://spreecommerce.org
    email: [email protected]
  description: |
    Spree Admin API v3 - Administrative API for managing products, orders, and store settings.

    ## Authentication

    The Admin API requires a secret API key passed in the `x-spree-api-key` header.
    Secret API keys can be generated in the Spree admin dashboard.

    ## Response Format

    All responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.
    Single resource endpoints return a flat JSON object.

    ## Resource IDs

    Every resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,
    `variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,
    request bodies, and Ransack filters all accept them directly.

    ## Error Handling

    Errors return a consistent format:
    ```json
    {
      "error": {
        "code": "validation_error",
        "message": "Validation failed",
        "details": { "name": ["can't be blank"] }
      }
    }
    ```
  version: v3
paths:
  "/api/v3/admin/auth/login":
    post:
      summary: Login
      tags:
      - Authentication
      security:
      - api_key: []
      description: |
        Authenticates an admin user and returns a short-lived JWT access token.
        The rotatable refresh token is set in an HttpOnly cookie — it is not
        included in the response body.

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

        To authenticate against a third-party identity provider (Okta, Azure AD,
        Google Workspace SSO, a custom JWT issuer, SAML, etc.), send
        `{ "provider": "<your_key>", ... }` with the fields that provider
        requires. The endpoint returns the same JWT regardless of which provider
        authenticated the request. See
        [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)
        for the list of configured providers and their required fields.
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // The refresh token is set as an HttpOnly cookie; only `token` and `user` come back in the body.
          const auth = await client.auth.login({
            email: '[email protected]',
            password: 'password123',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /auth/login -d '{"email":"[email protected]","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.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjE3NmVlN2M3LWJkYzktNGM1MS1hMzFiLTEwMDYxOTc3NGZmNCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDc4NzAwfQ.t4Ntas5E8dwfI8wxMdwcC-XVFXWzaFSAFL8_Mv4HnlU
                user:
                  id: adm_UkLWZg9DAJ
                  email: [email protected]
                  first_name: Gavin
                  last_name: Swift
                  full_name: Gavin Swift
                  selected_locale:
                  status: active
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  last_active_at: '2026-01-15T12:00:00Z'
                  avatar_url:
                  roles:
                  - id: role_UkLWZg9DAJ
                    name: admin
                  stores:
                  - id: store_UkLWZg9DAJ
                    name: Spree Test Store
                    code: spree_1
              schema:
                "$ref": "#/components/schemas/AuthResponse"
        '401':
          description: invalid credentials
          content:
            application/json:
              example:
                error:
                  code: authentication_failed
                  message: Invalid email or password
              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: [email protected]
                  password:
                    type: string
                    example: password123
                required:
                - email
                - password
              - title: ProviderLogin
                description: |
                  Provider-dispatched login. The `provider` key selects a configured
                  authentication provider; the remaining fields are forwarded to it.
                  Required fields depend on the provider — see
                  [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).
                type: object
                properties:
                  provider:
                    type: string
                    example: okta
                    description: Registered provider key (anything other than `email`).
                    not:
                      enum:
                      - email
                required:
                - provider
                additionalProperties: true
  "/api/v3/admin/auth/refresh":
    post:
      summary: Refresh token
      tags:
      - Authentication
      security:
      - api_key: []
      description: |
        Exchanges the HttpOnly refresh-token cookie for a new access JWT and a
        rotated refresh token cookie. No request body or Authorization header
        is required — the cookie alone authenticates the call.
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Driven entirely by the HttpOnly refresh-token cookie + CSRF header (set by the SDK).
          const auth = await client.auth.refresh()
      - lang: bash
        label: Spree CLI
        source: spree api post /auth/refresh
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: refresh successful
          content:
            application/json:
              example:
                token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImFiN2M4YjAxLTY0MGYtNDJhZi1hZTY1LTQxY2NmOTk1YmVlMCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDc4NzAwfQ.oXS2FwkI2rK4WOX4QUNW4oTPu7gzMmB9Y9oqsJpW7SY
                user:
                  id: adm_UkLWZg9DAJ
                  email: [email protected]
                  first_name: Clarine
                  last_name: Jenkins
                  full_name: Clarine Jenkins
                  selected_locale:
                  status: active
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  last_active_at: '2026-01-15T12:00:00Z'
                  avatar_url:
                  roles:
                  - id: role_UkLWZg9DAJ
                    name: admin
                  stores:
                  - id: store_UkLWZg9DAJ
                    name: Spree Test Store
                    code: spree_1
              schema:
                "$ref": "#/components/schemas/AuthResponse"
        '401':
          description: missing or invalid refresh-token cookie
          content:
            application/json:
              example:
                error:
                  code: invalid_refresh_token
                  message: Refresh token cookie missing
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/admin/auth/logout":
    post:
      summary: Logout
      tags:
      - Authentication
      security:
      - api_key: []
      description: Revokes the refresh-token cookie, effectively logging the admin
        out.
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.auth.logout()
      - lang: bash
        label: Spree CLI
        source: spree api post /auth/logout
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '204':
          description: logout successful
  "/api/v3/admin/auth/invitations/{id}/accept":
    parameters:
    - name: id
      in: path
      description: Invitation ID from the emailed link
      required: true
      schema:
        type: string
    post:
      summary: Accept an invitation
      tags:
      - Authentication
      description: |
        Accepts a staff invitation and returns a signed-in admin session, so the
        new member lands in the dashboard rather than on a login form.

        Unauthenticated — the ID and token in the emailed link are the
        credential. The email is never taken from the request; it always comes
        from the invitation.

        `password` is required when no account exists for the invited address,
        in which case it sets one. When an account already exists, the same
        field is how the person proves the account is theirs — unless the
        request carries that account's own access token, which proves it
        already.
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // The invitation ID and token come from the link in the invitation email.
          // An invitee without an account sets a password here; one with an account
          // signs in with theirs. The refresh token is set as an HttpOnly cookie.
          const auth = await client.auth.acceptInvitation('inv_UkLWZg9DAJ', 'xK3pQ9vLmT2wRz8N', {
            password: 'password123',
            password_confirmation: 'password123',
            first_name: 'Robin',
            last_name: 'Ellis',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /auth/invitations/{id}/accept -d '{"password":"password123","password_confirmation":"password123","first_name":"Robin","last_name":"Ellis"}'
      parameters:
      - name: token
        in: query
        required: true
        description: The token from the emailed link
        schema:
          type: string
      responses:
        '200':
          description: invitation accepted, session issued
          content:
            application/json:
              example:
                token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjQ2MzZlMDBiLTdmZGMtNDk1Mi1hNzhhLTI4YmEyMTVjNDk0MSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDc4NzAwfQ.AwpPaRCvRIV36C8k4nChul5s7yq_yWFTSy_TyVlrbXA
                user:
                  id: adm_gbHJdmfrXB
                  email: [email protected]
                  first_name: Robin
                  last_name: Ellis
                  full_name: Robin Ellis
                  selected_locale:
                  status: active
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  last_active_at: '2026-01-15T12:00:00Z'
                  avatar_url:
                  roles:
                  - id: role_UkLWZg9DAJ
                    name: admin
                  stores:
                  - id: store_UkLWZg9DAJ
                    name: Spree Test Store
                    code: spree_1
              schema:
                "$ref": "#/components/schemas/AuthResponse"
        '404':
          description: wrong token, or an invitation that can no longer be accepted
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Invitation not found, expired, or already accepted
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/InvitationAcceptParams"
        required: true
  "/api/v3/admin/me":
    get:
      summary: Get current admin user and permissions
      tags:
      - Authentication
      security:
      - api_key: []
        bearer_auth: []
      description: Returns the current admin user profile and a serialized list of
        permissions (CanCanCan rules). The SPA uses these to drive UI permission checks.
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const me = await client.me.get()
          if (
            me.permissions.some(
              (r) => r.allow && r.actions.includes('manage') && r.subjects.includes('product'),
            )
          ) {
            // show "Create product" button
          }
      - lang: bash
        label: Spree CLI
        source: spree api get /me
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: current admin user and permissions
          content:
            application/json:
              example:
                user:
                  id: adm_UkLWZg9DAJ
                  email: [email protected]
                  first_name: Zenobia
                  last_name: Sanford
                  full_name: Zenobia Sanford
                  selected_locale:
                  status: active
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  last_active_at:
                  avatar_url:
                  roles:
                  - id: role_UkLWZg9DAJ
                    name: admin
                  stores:
                  - id: store_UkLWZg9DAJ
                    name: Spree Test Store
                    code: spree_1
                permissions:
                - allow: true
                  actions:
                  - manage
                  subjects:
                  - all
                  has_conditions: false
                permission_keys:
                - read_dashboard
                - read_reports
                - write_reports
                - read_orders
                - write_orders
                - read_payments
                - write_payments
                - read_fulfillments
                - write_fulfillments
                - read_refunds
                - write_refunds
                - read_products
                - write_products
                - read_product_types
                - write_product_types
                - read_publishing
                - write_publishing
                - read_media
                - write_media
                - read_categories
                - write_categories
                - read_collections
                - write_collections
                - read_stock
                - write_stock
                - read_purchasing
                - write_purchasing
                - read_customers
                - write_customers
                - read_sellers
                - write_sellers
                - read_commissions
                - write_commissions
                - read_payouts
                - write_payouts
                - read_gift_cards
                - write_gift_cards
                - read_store_credits
                - write_store_credits
                - read_promotions
                - write_promotions
                - read_settings
                - write_settings
                - read_delivery_methods
                - write_delivery_methods
                - read_package_types
                - write_package_types
                - read_webhooks
                - write_webhooks
                - read_email_templates
                - write_email_templates
                - read_integrations
                - write_integrations
                - read_maintenance_tasks
                - write_maintenance_tasks
                - read_api_keys
                - write_api_keys
                - read_oauth_applications
                - write_oauth_applications
                - read_staff
                - write_staff
              schema:
                "$ref": "#/components/schemas/MeResponse"
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update the current admin profile
      tags:
      - Authentication
      security:
      - api_key: []
        bearer_auth: []
      description: Self-service update of the signed-in admin's own profile, such
        as their admin UI display language (`selected_locale`).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Set the signed-in admin's own UI display language.
          const me = await client.me.update({
            selected_locale: 'de',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /me -d '{"selected_locale":"de"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: profile updated
          content:
            application/json:
              example:
                user:
                  id: adm_UkLWZg9DAJ
                  email: [email protected]
                  first_name: See
                  last_name: Kuhlman
                  full_name: See Kuhlman
                  selected_locale: de
                  status: active
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  last_active_at:
                  avatar_url:
                  roles:
                  - id: role_UkLWZg9DAJ
                    name: admin
                  stores:
                  - id: store_UkLWZg9DAJ
                    name: Spree Test Store
                    code: spree_1
                permissions:
                - allow: true
                  actions:
                  - manage
                  subjects:
                  - all
                  has_conditions: false
                permission_keys:
                - read_dashboard
                - read_reports
                - write_reports
                - read_orders
                - write_orders
                - read_payments
                - write_payments
                - read_fulfillments
                - write_fulfillments
                - read_refunds
                - write_refunds
                - read_products
                - write_products
                - read_product_types
                - write_product_types
                - read_publishing
                - write_publishing
                - read_media
                - write_media
                - read_categories
                - write_categories
                - read_collections
                - write_collections
                - read_stock
                - write_stock
                - read_purchasing
                - write_purchasing
                - read_customers
                - write_customers
                - read_sellers
                - write_sellers
                - read_commissions
                - write_commissions
                - read_payouts
                - write_payouts
                - read_gift_cards
                - write_gift_cards
                - read_store_credits
                - write_store_credits
                - read_promotions
                - write_promotions
                - read_settings
                - write_settings
                - read_delivery_methods
                - write_delivery_methods
                - read_package_types
                - write_package_types
                - read_webhooks
                - write_webhooks
                - read_email_templates
                - write_email_templates
                - read_integrations
                - write_integrations
                - read_maintenance_tasks
                - write_maintenance_tasks
                - read_api_keys
                - write_api_keys
                - read_oauth_applications
                - write_oauth_applications
                - read_staff
                - write_staff
              schema:
                "$ref": "#/components/schemas/MeResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MeUpdateParams"
        required: true
  "/api/v3/admin/auth/password_resets":
    post:
      summary: Request password reset
      tags:
      - Authentication
      security:
      - api_key: []
      description: |
        Requests a password reset email for an admin user. Always returns `202`
        whether or not the email matches an account, to prevent enumeration.

        `redirect_url` is where the emailed link should point (the reset token
        is appended as a `token` query param). It is honoured only on the
        dashboard's origin and for an account that is staff of the store —
        otherwise it is silently ignored and the link opens the dashboard's
        reset page. The email is delivered by Spree itself via the
        `admin_user.password_reset_requested` event; this event is never
        forwarded to webhook endpoints.
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Always resolves (202) whether or not the email exists — no account enumeration.
          // The emailed link points at redirect_url with the reset token appended as ?token=.
          await client.auth.requestPasswordReset({
            email: '[email protected]',
            redirect_url: 'https://admin.your-store.com/reset-password',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /auth/password_resets -d '{"email":"[email protected]","redirect_url":"https://admin.your-store.com/reset-password"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '202':
          description: reset requested
          content:
            application/json:
              example:
                message: If an account exists for that email, password reset instructions
                  have been sent.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PasswordResetRequestParams"
        required: true
  "/api/v3/admin/auth/password_resets/{id}":
    patch:
      summary: Reset password
      tags:
      - Authentication
      security:
      - api_key: []
      description: |
        Consumes a password reset token (the `token` query param from the
        emailed link), sets the new password, and signs the admin in: the
        response carries a JWT access token and the rotatable refresh token is
        set in an HttpOnly cookie. The token is single-use — it invalidates as
        soon as the password changes.
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // The token comes from the emailed link's ?token= param. On success the admin
          // is signed in: a JWT comes back and the refresh token is set as an HttpOnly cookie.
          const auth = await client.auth.resetPassword('reset-token-from-email', {
            password: 'new-password-123',
            password_confirmation: 'new-password-123',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /auth/password_resets/{id} -d '{"password":"new-password-123","password_confirmation":"new-password-123"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: The reset token from the emailed link
        required: true
        schema:
          type: string
      responses:
        '200':
          description: password reset
          content:
            application/json:
              example:
                token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjBiZTdhM2RmLWEyYzYtNDZkOC1hNTZiLWE4NDg4MGIyZGZiNCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.Vo2RzprqsH2XBa8DaSQ6awyXqlBA5QDFA5R7ygTezXY
                user:
                  id: adm_UkLWZg9DAJ
                  email: [email protected]
                  first_name: Olga
                  last_name: Schneider
                  full_name: Olga Schneider
                  selected_locale:
                  status: active
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  last_active_at: '2026-01-15T12:00:00Z'
                  avatar_url:
                  roles:
                  - id: role_UkLWZg9DAJ
                    name: admin
                  stores:
                  - id: store_UkLWZg9DAJ
                    name: Spree Test Store
                    code: spree_1
              schema:
                "$ref": "#/components/schemas/AuthResponse"
        '422':
          description: invalid or expired token
          content:
            application/json:
              example:
                error:
                  code: password_reset_token_invalid
                  message: Password reset token is invalid or has expired.
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PasswordResetParams"
        required: true
  "/api/v3/admin/auth/setup":
    get:
      summary: Check first-run setup availability
      tags:
      - Authentication
      description: |
        Reports whether first-run setup is still available — true only while
        the installation has no admin user. Unauthenticated; the dashboard
        login page uses it to offer the setup screen.
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // True only until the installation has its first admin user.
          const { setup_required } = await client.auth.setupStatus()
      - lang: bash
        label: Spree CLI
        source: spree api get /auth/setup
      responses:
        '200':
          description: setup status
          content:
            application/json:
              example:
                setup_required: true
    post:
      summary: Complete first-run setup
      tags:
      - Authentication
      description: |
        Creates the first admin account and adopts the seeded store, authorized
        by the one-time setup token printed at install time (rotate it with
        `bin/rails spree:setup:token`). Issues a JWT access token and a
        refresh-token cookie exactly like login. Returns 404 once any admin
        user exists — the flow is closed permanently after setup.
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // The setup token is printed when Spree is installed. The refresh token is
          // set as an HttpOnly cookie; only `token` and `user` come back in the body.
          const auth = await client.auth.completeSetup({
            setup_token: 'st_9f2c4e7a1b8d',
            email: '[email protected]',
            password: 'Secret123!',
            password_confirmation: 'Secret123!',
            first_name: 'Olivia',
            last_name: 'Owner',
            store_name: 'My Store',
            country_code: 'US',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /auth/setup -d '{"setup_token":"st_9f2c4e7a1b8d","email":"[email protected]","password":"Secret123!","password_confirmation":"Secret123!","first_name":"Olivia","last_name":"Owner","store_name":"My
          Store","country_code":"US"}'
      parameters: []
      responses:
        '200':
          description: setup completed
          content:
            application/json:
              example:
                token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjZjMjg1ODk5LTExMzUtNDBhMi1hNDBiLTE4NjNiODcwZDRjYyIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDc4NzAwfQ.Go2eUEiXf7rVD5mwtNMqkWqUGcBfhxk3b7JT8dw8uiE
                user:
                  id: adm_UkLWZg9DAJ
                  email: [email protected]
                  first_name: Olivia
                  last_name: Owner
                  full_name: Olivia Owner
                  selected_locale:
                  status: active
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  last_active_at: '2026-01-15T12:00:00Z'
                  avatar_url:
                  roles:
                  - id: role_UkLWZg9DAJ
                    name: admin
                  stores:
                  - id: store_UkLWZg9DAJ
                    name: My Store
                    code: spree_1
        '404':
          description: setup not available
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Setup is not available
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/SetupParams"
        required: true
  "/api/v3/admin/auth/setup/countries":
    get:
      summary: List countries for first-run setup
      tags:
      - Authentication
      description: |
        Countries the store can be set up in, each with the currency and
        official languages derived from it. Unauthenticated, because the setup
        screen runs before any credential exists. Returns 404 once any admin
        user exists.
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Each country comes with the currency and languages the store would start with.
          const { countries } = await client.auth.setupCountries()
      - lang: bash
        label: Spree CLI
        source: spree api get /auth/setup/countries
      responses:
        '200':
          description: countries
          content:
            application/json:
              example:
                countries:
                - code: AD
                  currency: EUR
                  locales:
                  - ca
                - code: AE
                  currency: AED
                  locales:
                  - ar
                - code: AF
                  currency: AFN
                  locales:
                  - ps
                  - uz
                  - tk
                - code: AG
                  currency: XCD
                  locales:
                  - en
                - code: AI
                  currency: XCD
                  locales:
                  - en
                - code: AL
                  currency: ALL
                  locales:
                  - sq
                - code: AM
                  currency: AMD
                  locales:
                  - hy
                - code: AO
                  currency: AOA
                  locales:
                  - pt
                - code: AR
                  currency: ARS
                  locales:
                  - es
                  - gn
                - code: AS
                  currency: USD
                  locales:
                  - en
                  - sm
                - code: AT
                  currency: EUR
                  locales:
                  - de
                - code: AU
                  currency: AUD
                  locales:
                  - en
                - code: AW
                  currency: AWG
                  locales:
                  - nl
                - code: AZ
                  currency: AZN
                  locales:
                  - az
                  - hy
                - code: BA
                  currency: BAM
                  locales:
                  - bs
                  - hr
                  - sr
                - code: BB
                  currency: BBD
                  locales:
                  - en
                - code: BD
                  currency: BDT
                  locales:
                  - bn
                - code: BE
                  currency: EUR
                  locales:
                  - nl
                  - fr
                  - de
                - code: BF
                  currency: XOF
                  locales:
                  - fr
                  - ff
                - code: BG
                  currency: EUR
                  locales:
                  - bg
                - code: BH
                  currency: BHD
                  locales:
                  - ar
                - code: BI
                  currency: BIF
                  locales:
                  - fr
                  - rn
                - code: BJ
                  currency: XOF
                  locales:
                  - fr
                - code: BL
                  currency: EUR
                  locales:
                  - fr
                - code: BM
                  currency: BMD
                  locales:
                  - en
                - code: BN
                  currency: BND
                  locales:
                  - ms
                - code: BO
                  currency: BOB
                  locales:
                  - es
                  - ay
                  - qu
                - code: BQ
                  currency: USD
                  locales:
                  - nl
                  - en
                - code: BR
                  currency: BRL
                  locales:
                  - pt
                - code: BS
                  currency: BSD
                  locales:
                  - en
                - code: BT
                  currency: BTN
                  locales:
                  - dz
                - code: BW
                  currency: BWP
                  locales:
                  - en
                  - tn
                - code: BY
                  currency: BYN
                  locales:
                  - be
                  - ru
                - code: BZ
                  currency: BZD
                  locales:
                  - en
                  - es
                - code: CA
                  currency: CAD
                  locales:
                  - en
                  - fr
                - code: CC
                  currency: AUD
                  locales:
                  - en
                - code: CD
                  currency: CDF
                  locales:
                  - fr
                  - ln
                  - kg
                  - sw
                  - lu
                - code: CF
                  currency: XAF
                  locales:
                  - fr
                  - sg
                - code: CG
                  currency: XAF
                  locales:
                  - fr
                  - ln
                - code: CH
                  currency: CHF
                  locales:
                  - de
                  - fr
                  - it
                  - rm
                - code: CI
                  currency: XOF
                  locales:
                  - fr
                - code: CK
                  currency: NZD
                  locales:
                  - en
                - code: CL
                  currency: CLP
                  locales:
                  - es
                - code: CM
                  currency: XAF
                  locales:
                  - en
                  - fr
                - code: CN
                  currency: CNY
                  locales:
                  - zh-CN
                - code: CO
                  currency: COP
                  locales:
                  - es
                - code: CR
                  currency: CRC
                  locales:
                  - es
                - code: CU
                  currency: CUP
                  locales:
                  - es
                - code: CV
                  currency: CVE
                  locales:
                  - pt
                - code: CW
                  currency: XCG
                  locales:
                  - nl
                - code: CX
                  currency: AUD
                  locales:
                  - en
                  - zh-CN
                  - ms
                - code: CY
                  currency: EUR
                  locales:
                  - el
                  - tr
                  - hy
                - code: CZ
                  currency: CZK
                  locales:
                  - cs
                - code: DE
                  currency: EUR
                  locales:
                  - de
                - code: DJ
                  currency: DJF
                  locales:
                  - ar
                  - fr
                - code: DK
                  currency: DKK
                  locales:
                  - da
                - code: DM
                  currency: XCD
                  locales:
                  - en
                - code: DO
                  currency: DOP
                  locales:
                  - es
                - code: DZ
                  currency: DZD
                  locales:
                  - ar
                - code: EC
                  currency: USD
                  locales:
                  - es
                - code: EE
                  currency: EUR
                  locales:
                  - et
                - code: EG
                  currency: EGP
                  locales:
                  - ar
                - code: ER
                  currency: ERN
                  locales:
                  - en
                  - ar
                  - ti
                - code: ES
                  currency: EUR
                  locales:
                  - es
                - code: ET
                  currency: ETB
                  locales:
                  - am
                - code: FI
                  currency: EUR
                  locales:
                  - fi
                  - sv
                - code: FJ
                  currency: FJD
                  locales:
                  - en
                  - fj
                  - hi
                - code: FK
                  currency: FKP
                  locales:
                  - en
                - code: FM
                  currency: USD
                  locales:
                  - en
                - code: FO
                  currency: DKK
                  locales:
                  - fo
                - code: FR
                  currency: EUR
                  locales:
                  - fr
                - code: GA
                  currency: XAF
                  locales:
                  - fr
                - code: GB
                  currency: GBP
                  locales:
                  - en
                - code: GD
                  currency: XCD
                  locales:
                  - en
                - code: GE
                  currency: GEL
                  locales:
                  - ka
                - code: GF
                  currency: EUR
                  locales:
                  - fr
                - code: GG
                  currency: GBP
                  locales:
                  - en
                  - fr
                - code: GH
                  currency: GHS
                  locales:
                  - en
                - code: GI
                  currency: GIP
                  locales:
                  - en
                - code: GL
                  currency: DKK
                  locales:
                  - kl
                - code: GM
                  currency: GMD
                  locales:
                  - en
                - code: GN
                  currency: GNF
                  locales:
                  - fr
                  - ff
                - code: GP
                  currency: EUR
                  locales:
                  - fr
                - code: GQ
                  currency: XAF
                  locales:
                  - es
                  - fr
                - code: GR
                  currency: EUR
                  locales:
                  - el
                - code: GT
                  currency: GTQ
                  locales:
                  - es
                - code: GU
                  currency: USD
                  locales:
                  - en
                  - ch
                  - es
                - code: GW
                  currency: XOF
                  locales:
                  - pt
                - code: GY
                  currency: GYD
                  locales:
                  - en
                - code: HK
                  currency: HKD
                  locales:
                  - en
                  - zh-CN
                - code: HN
                  currency: HNL
                  locales:
                  - es
                - code: HR
                  currency: EUR
                  locales:
                  - hr
                - code: HT
                  currency: HTG
                  locales:
                  - fr
                  - ht
                - code: HU
                  currency: HUF
                  locales:
                  - hu
                - code: ID
                  currency: IDR
                  locales:
                  - id
                - code: IE
                  currency: EUR
                  locales:
                  - en
                  - ga
                - code: IL
                  currency: ILS
                  locales:
                  - he
                  - ar
                - code: IM
                  currency: GBP
                  locales:
                  - en
                  - gv
                - code: IN
                  currency: INR
                  locales:
                  - hi
                  - en
                - code: IQ
                  currency: IQD
                  locales:
                  - ar
                - code: IR
                  currency: IRR
                  locales:
                  - fa
                - code: IS
                  currency: ISK
                  locales:
                  - is
                - code: IT
                  currency: EUR
                  locales:
                  - it
                - code: JE
                  currency: GBP
                  locales:
                  - en
                  - fr
                - code: JM
                  currency: JMD
                  locales:
                  - en
                - code: JO
                  currency: JOD
                  locales:
                  - ar
                - code: JP
                  currency: JPY
                  locales:
                  - ja
                - code: KE
                  currency: KES
                  locales:
                  - en
                  - sw
                - code: KG
                  currency: KGS
                  locales:
                  - ky
                  - ru
                - code: KH
                  currency: KHR
                  locales:
                  - km
                - code: KI
                  currency: AUD
                  locales:
                  - en
                - code: KM
                  currency: KMF
                  locales:
                  - ar
                  - fr
                - code: KN
                  currency: XCD
                  locales:
                  - en
                - code: KP
                  currency: KPW
                  locales:
                  - ko
                - code: KR
                  currency: KRW
                  locales:
                  - ko
                - code: KW
                  currency: KWD
                  locales:
                  - ar
                - code: KY
                  currency: KYD
                  locales:
                  - en
                - code: KZ
                  currency: KZT
                  locales:
                  - kk
                  - ru
                - code: LA
                  currency: LAK
                  locales:
                  - lo
                - code: LB
                  currency: LBP
                  locales:
                  - ar
                  - fr
                - code: LC
                  currency: XCD
                  locales:
                  - en
                - code: LI
                  currency: CHF
                  locales:
                  - de
                - code: LK
                  currency: LKR
                  locales:
                  - si
                  - ta
                - code: LR
                  currency: LRD
                  locales:
                  - en
                - code: LS
                  currency: LSL
                  locales:
                  - en
                  - st
                - code: LT
                  currency: EUR
                  locales:
                  - lt
                - code: LU
                  currency: EUR
                  locales:
                  - fr
                  - de
                  - lb
                - code: LV
                  currency: EUR
                  locales:
                  - lv
                - code: LY
                  currency: LYD
                  locales:
                  - ar
                - code: MA
                  currency: MAD
                  locales:
                  - ar
                - code: MC
                  currency: EUR
                  locales:
                  - fr
                - code: MD
                  currency: MDL
                  locales:
                  - ro
                - code: ME
                  currency: EUR
                  locales:
                  - sr
                  - bs
                  - sq
                  - hr
                - code: MF
                  currency: EUR
                  locales:
                  - en
                  - fr
                  - nl
                - code: MG
                  currency: MGA
                  locales:
                  - fr
                  - mg
                - code: MH
                  currency: USD
                  locales:
                  - en
                  - mh
                - code: MK
                  currency: MKD
                  locales:
                  - mk
                - code: ML
                  currency: XOF
                  locales:
                  - fr
                - code: MM
                  currency: MMK
                  locales:
                  - my
                - code: MN
                  currency: MNT
                  locales:
                  - mn
                - code: MO
                  currency: MOP
                  locales:
                  - zh-CN
                  - pt
                - code: MP
                  currency: USD
                  locales:
                  - en
                  - ch
                - code: MQ
                  currency: EUR
                  locales:
                  - fr
                - code: MR
                  currency: MRU
                  locales:
                  - ar
                  - fr
                - code: MS
                  currency: XCD
                  locales:
                  - en
                - code: MT
                  currency: EUR
                  locales:
                  - mt
                  - en
                - code: MU
                  currency: MUR
                  locales:
                  - en
                - code: MV
                  currency: MVR
                  locales:
                  - dv
                - code: MW
                  currency: MWK
                  locales:
                  - en
                  - ny
                - code: MX
                  currency: MXN
                  locales:
                  - es
                - code: MY
                  currency: MYR
                  locales:
                  - ms
                  - en
                - code: MZ
                  currency: MZN
                  locales:
                  - pt
                - code: NA
                  currency: NAD
                  locales:
                  - en
                  - af
                - code: NC
                  currency: XPF
                  locales:
                  - fr
                - code: NE
                  currency: XOF
                  locales:
                  - fr
                - code: NF
                  currency: AUD
                  locales:
                  - en
                - code: NG
                  currency: NGN
                  locales:
                  - en
                - code: NI
                  currency: NIO
                  locales:
                  - es
                - code: NL
                  currency: EUR
                  locales:
                  - nl
                - code: 'NO'
                  currency: NOK
                  locales:
                  - nb
                  - nn
                - code: NP
                  currency: NPR
                  locales:
                  - ne
                - code: NR
                  currency: AUD
                  locales:
                  - en
                  - na
                - code: NU
                  currency: NZD
                  locales:
                  - en
                - code: NZ
                  currency: NZD
                  locales:
                  - en
                - code: OM
                  currency: OMR
                  locales:
                  - ar
                - code: PA
                  currency: PAB
                  locales:
                  - es
                - code: PE
                  currency: PEN
                  locales:
                  - es
                - code: PF
                  currency: XPF
                  locales:
                  - fr
                - code: PG
                  currency: PGK
                  locales:
                  - en
                - code: PH
                  currency: PHP
                  locales:
                  - tl
                  - en
                - code: PK
                  currency: PKR
                  locales:
                  - en
                  - ur
                - code: PL
                  currency: PLN
                  locales:
                  - pl
                - code: PM
                  currency: EUR
                  locales:
                  - fr
                - code: PN
                  currency: NZD
                  locales:
                  - en
                - code: PR
                  currency: USD
                  locales:
                  - es
                  - en
                - code: PS
                  currency: ILS
                  locales:
                  - ar
                  - he
                  - en
                - code: PT
                  currency: EUR
                  locales:
                  - pt
                - code: PW
                  currency: USD
                  locales:
                  - en
                - code: PY
                  currency: PYG
                  locales:
                  - es
                  - gn
                - code: QA
                  currency: QAR
                  locales:
                  - ar
                - code: RE
                  currency: EUR
                  locales:
                  - fr
                - code: RO
                  currency: RON
                  locales:
                  - ro
                - code: RS
                  currency: RSD
                  locales:
                  - sr
                - code: RU
                  currency: RUB
                  locales:
                  - ru
                - code: RW
                  currency: RWF
                  locales:
                  - rw
                  - en
                  - fr
                - code: SA
                  currency: SAR
                  locales:
                  - ar
                - code: SB
                  currency: SBD
                  locales:
                  - en
                - code: SC
                  currency: SCR
                  locales:
                  - fr
                  - en
                - code: SD
                  currency: SDG
                  locales:
                  - ar
                  - en
                - code: SE
                  currency: SEK
                  locales:
                  - sv
                - code: SG
                  currency: SGD
                  locales:
                  - en
                  - ms
                  - ta
                - code: SH
                  currency: SHP
                  locales:
                  - en
                - code: SI
                  currency: EUR
                  locales:
                  - sl
                - code: SJ
                  currency: NOK
                  locales:
                  - 'no'
                - code: SK
                  currency: EUR
                  locales:
                  - sk
                - code: SL
                  currency: SLE
                  locales:
                  - en
                - code: SM
                  currency: EUR
                  locales:
                  - it
                - code: SN
                  currency: XOF
                  locales:
                  - fr
                - code: SO
                  currency: SOS
                  locales:
                  - so
                  - ar
                - code: SR
                  currency: SRD
                  locales:
                  - nl
                - code: SS
                  currency: SSP
                  locales:
                  - ar
                  - en
                - code: ST
                  currency: STN
                  locales:
                  - pt
                - code: SV
                  currency: USD
                  locales:
                  - es
                - code: SX
                  currency: XCG
                  locales:
                  - nl
                  - en
                - code: SY
                  currency: SYP
                  locales:
                  - ar
                - code: SZ
                  currency: SZL
                  locales:
                  - en
                  - ss
                - code: TC
                  currency: USD
                  locales:
                  - en
                - code: TD
                  currency: XAF
                  locales:
                  - ar
                  - fr
                - code: TG
                  currency: XOF
                  locales:
                  - fr
                - code: TH
                  currency: THB
                  locales:
                  - th
                - code: TJ
                  currency: TJS
                  locales:
                  - tg
                  - ru
                - code: TK
                  currency: NZD
                  locales:
                  - en
                - code: TL
                  currency: IDR
                  locales:
                  - pt
                - code: TM
                  currency: TMT
                  locales:
                  - tk
                - code: TN
                  currency: TND
                  locales:
                  - ar
                  - fr
                - code: TO
                  currency: TOP
                  locales:
                  - en
                  - to
                - code: TR
                  currency: TRY
                  locales:
                  - tr
                - code: TT
                  currency: TTD
                  locales:
                  - en
                - code: TV
                  currency: AUD
                  locales:
                  - en
                - code: TW
                  currency: TWD
                  locales:
                  - zh-CN
                - code: TZ
                  currency: TZS
                  locales:
                  - sw
                  - en
                - code: UA
                  currency: UAH
                  locales:
                  - uk
                - code: UG
                  currency: UGX
                  locales:
                  - en
                  - sw
                - code: US
                  currency: USD
                  locales:
                  - en
                - code: UY
                  currency: UYU
                  locales:
                  - es
                - code: UZ
                  currency: UZS
                  locales:
                  - uz
                - code: VA
                  currency: EUR
                  locales:
                  - it
                  - la
                - code: VC
                  currency: XCD
                  locales:
                  - en
                - code: VE
                  currency: VES
                  locales:
                  - es
                - code: VG
                  currency: USD
                  locales:
                  - en
                - code: VI
                  currency: USD
                  locales:
                  - en
                - code: VN
                  currency: VND
                  locales:
                  - vi
                - code: VU
                  currency: VUV
                  locales:
                  - bi
                  - en
                  - fr
                - code: WF
                  currency: XPF
                  locales:
                  - fr
                - code: WS
                  currency: WST
                  locales:
                  - sm
                  - en
                - code: YE
                  currency: YER
                  locales:
                  - ar
                - code: YT
                  currency: EUR
                  locales:
                  - fr
                - code: ZA
                  currency: ZAR
                  locales:
                  - af
                  - en
                  - nr
                  - st
                  - ss
                  - tn
                  - ts
                  - ve
                  - xh
                  - zu
                - code: ZM
                  currency: ZMW
                  locales:
                  - en
                - code: ZW
                  currency: USD
                  locales:
                  - en
                  - sn
                  - nd
  "/api/v3/admin/allowed_origins":
    get:
      summary: List allowed origins
      tags:
      - Allowed Origins
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the CORS allowlist for the current store. Each entry is a
        bare `scheme://host[:port]` permitted to call the admin API from a
        browser. Backs the `Rack::Cors` allowlist and the CSRF boundary of
        the admin cookie session (see
        `docs/plans/5.5-admin-auth-cookie-refresh.md`).


        **Required scope:** `read_api_keys` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: origins } = await client.allowedOrigins.list()
      - lang: bash
        label: Spree CLI
        source: spree api get /allowed_origins
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of origin (partial, case-insensitive).
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      - name: sort
        in: query
        required: false
        description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include. id is always included.
        schema:
          type: string
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[origin_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `origin` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `origin`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: AllowedOrigin
        sortable:
        - created_at
        - id
        - origin
        - updated_at
      responses:
        '200':
          description: allowed origins found
          content:
            application/json:
              example:
                data:
                - id: ao_UkLWZg9DAJ
                  origin: https://shop.example.com
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                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/AllowedOrigin"
                  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"
    post:
      summary: Create an allowed origin
      tags:
      - Allowed Origins
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Adds an origin to the admin CORS allowlist. The value must be a bare
        `scheme://host[:port]` (no path, query, or fragment) and use `http` or
        `https`.


        **Required scope:** `write_api_keys` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const origin = await client.allowedOrigins.create({
            origin: 'https://admin.example.com',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /allowed_origins -d '{"origin":"https://admin.example.com"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '201':
          description: allowed origin created
          content:
            application/json:
              example:
                id: ao_gbHJdmfrXB
                origin: https://admin.example.com
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/AllowedOrigin"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Origin is invalid
                  details:
                    origin:
                    - code: invalid
                      message: is invalid
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AllowedOriginCreateParams"
        required: true
  "/api/v3/admin/allowed_origins/{id}":
    parameters:
    - name: id
      in: path
      required: true
      description: Allowed origin ID
      schema:
        type: string
    get:
      summary: Get an allowed origin
      tags:
      - Allowed Origins
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a single allowed origin by prefixed ID.

        **Required scope:** `read_api_keys` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const origin = await client.allowedOrigins.get('ao_xxx')
      - lang: bash
        label: Spree CLI
        source: spree api get /allowed_origins/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        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: allowed origin found
          content:
            application/json:
              example:
                id: ao_UkLWZg9DAJ
                origin: https://shop.example.com
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/AllowedOrigin"
        '404':
          description: allowed origin not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Allowed origin not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update an allowed origin
      tags:
      - Allowed Origins
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Updates an existing allowed origin.

        **Required scope:** `write_api_keys` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const origin = await client.allowedOrigins.update('ao_xxx', {
            origin: 'https://www.example.com',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /allowed_origins/{id} -d '{"origin":"https://www.example.com"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: allowed origin updated
          content:
            application/json:
              example:
                id: ao_UkLWZg9DAJ
                origin: https://www.example.com
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/AllowedOrigin"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Origin must be an origin (scheme and host) without path,
                    query, or fragment
                  details:
                    origin:
                    - code: must_be_origin_only
                      message: must be an origin (scheme and host) without path, query,
                        or fragment
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/AllowedOriginUpdateParams"
        required: true
    delete:
      summary: Delete an allowed origin
      tags:
      - Allowed Origins
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Removes an origin from the admin CORS allowlist. After deletion the
        admin SPA running at that origin will no longer be able to call the
        admin API from a browser.


        **Required scope:** `write_api_keys` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.allowedOrigins.delete('ao_xxx')
      - lang: bash
        label: Spree CLI
        source: spree api delete /allowed_origins/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '204':
          description: allowed origin deleted
  "/api/v3/admin/api_keys":
    get:
      summary: List API keys
      tags:
      - API Keys
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.

        **Required scope:** `read_api_keys` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: keys } = await client.apiKeys.list()
      - lang: bash
        label: Spree CLI
        source: spree api get /api_keys
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: ApiKey
        sortable:
        - created_at
        - id
        - name
        - updated_at
      responses:
        '200':
          description: API keys found
          content:
            application/json:
              example:
                data:
                - id: key_UkLWZg9DAJ
                  name: Storefront key
                  key_type: publishable
                  token_prefix:
                  scopes: []
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  revoked_at:
                  last_used_at:
                  channel_id:
                  plaintext_token: pk_K6zNkaVogFy735ukK6E7Qs1F
                  created_by_email:
                  created_by_type:
                  created_by_label:
                - id: key_gbHJdmfrXB
                  name: Backend integration
                  key_type: secret
                  token_prefix: sk_JiXS5S1gJ
                  scopes:
                  - write_all
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  revoked_at:
                  last_used_at:
                  channel_id:
                  plaintext_token:
                  created_by_email:
                  created_by_type:
                  created_by_label:
                - id: key_EfhxLZ9ck8
                  name: API key 13
                  key_type: secret
                  token_prefix: sk_vihKVmP6r
                  scopes:
                  - write_all
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  revoked_at:
                  last_used_at:
                  channel_id:
                  plaintext_token:
                  created_by_email:
                  created_by_type:
                  created_by_label:
                meta:
                  page: 1
                  limit: 25
                  count: 3
                  pages: 1
                  from: 1
                  to: 3
                  in: 3
                  previous:
                  next:
    post:
      summary: Create an API key
      tags:
      - API Keys
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use.

        **Required scope:** `write_api_keys` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const key = await client.apiKeys.create({
            name: 'Backend integration',
            key_type: 'secret',
            scopes: ['read_orders', 'write_orders'],
          })

          // `key.plaintext_token` is available only on this response.
      - lang: bash
        label: Spree CLI
        source: spree api post /api_keys -d '{"name":"Backend integration","key_type":"secret","scopes":["read_orders","write_orders"]}'
      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: secret key created — plaintext token returned once
          content:
            application/json:
              example:
                id: key_VqXmZF31wY
                name: CI key
                key_type: secret
                token_prefix: sk_kCkDUvba1
                scopes:
                - read_orders
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                revoked_at:
                last_used_at:
                channel_id:
                plaintext_token: sk_kCkDUvba1Z9gf8HAy29ih1Bj
                created_by_email: [email protected]
                created_by_type: admin_user
                created_by_label: Mana Cremin
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Name can't be blank and Scopes can't be blank
                  details:
                    name:
                    - code: blank
                      message: can't be blank
                      specific: false
                    scopes:
                    - code: blank
                      message: can't be blank
                      specific: false
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ApiKeyCreateParams"
        required: true
  "/api/v3/admin/api_keys/{id}":
    get:
      summary: Show an API key
      tags:
      - API Keys
      security:
      - api_key: []
        bearer_auth: []
      description: "**Required scope:** `read_api_keys` (for API-key authentication)."
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const key = await client.apiKeys.get('key_xxx')
      - lang: bash
        label: Spree CLI
        source: spree api get /api_keys/{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
        schema:
          type: string
      responses:
        '200':
          description: API key found
          content:
            application/json:
              example:
                id: key_UkLWZg9DAJ
                name: Storefront key
                key_type: publishable
                token_prefix:
                scopes: []
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                revoked_at:
                last_used_at:
                channel_id:
                plaintext_token: pk_XyZ9qSxtdtD6Uewb3GXYKkoV
                created_by_email:
                created_by_type:
                created_by_label:
    patch:
      summary: Update an API key
      tags:
      - API Keys
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Renames a key. `key_type` and `scopes` are fixed at creation — to change a key's authority, create a new key and revoke the old one.

        **Required scope:** `write_api_keys` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Only `name` is editable — scopes and key_type are fixed at creation.
          const key = await client.apiKeys.update('key_xxx', { name: 'CI key (renamed)' })
      - lang: bash
        label: Spree CLI
        source: spree api patch /api_keys/{id} -d '{"name":"CI key (renamed)"}'
      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: API key renamed
          content:
            application/json:
              example:
                id: key_gbHJdmfrXB
                name: Backend integration (renamed)
                key_type: secret
                token_prefix: sk_ZPBGFa2TH
                scopes:
                - write_all
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                revoked_at:
                last_used_at:
                channel_id:
                plaintext_token:
                created_by_email:
                created_by_type:
                created_by_label:
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ApiKeyUpdateParams"
        required: true
    delete:
      summary: Delete an API key
      tags:
      - API Keys
      security:
      - api_key: []
        bearer_auth: []
      description: "**Required scope:** `write_api_keys` (for API-key authentication)."
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.apiKeys.delete('key_xxx')
      - lang: bash
        label: Spree CLI
        source: spree api delete /api_keys/{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
        schema:
          type: string
      responses:
        '204':
          description: API key deleted
  "/api/v3/admin/api_keys/current":
    get:
      summary: Describe the current API key
      tags:
      - API Keys
      security:
      - api_key: []
      description: |-
        Returns the secret key that authenticated this request, including its live scopes. Useful to confirm a key's real, current authority. Only secret-key principals have a single key to describe.

        **Required scope:** none — any key can describe itself (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Describes the key you authenticated with, including its live scopes.
          const key = await client.apiKeys.current()
      - lang: bash
        label: Spree CLI
        source: spree api get /api_keys/current
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: current API key
          content:
            application/json:
              example:
                id: key_EfhxLZ9ck8
                name: API key 19
                key_type: secret
                token_prefix: sk_L5LVfygvH
                scopes:
                - write_all
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                revoked_at:
                last_used_at:
                channel_id:
                plaintext_token:
                created_by_email:
                created_by_type:
                created_by_label:
  "/api/v3/admin/api_keys/{id}/revoke":
    patch:
      summary: Revoke an API key
      tags:
      - API Keys
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.

        **Required scope:** `write_api_keys` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const key = await client.apiKeys.revoke('key_xxx')
      - lang: bash
        label: Spree CLI
        source: spree api patch /api_keys/{id}/revoke -d '{ ... }'
      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: API key revoked
          content:
            application/json:
              example:
                id: key_gbHJdmfrXB
                name: Backend integration
                key_type: secret
                token_prefix: sk_11yGX4rad
                scopes:
                - write_all
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                revoked_at: '2026-01-15T12:00:00.000Z'
                last_used_at:
                channel_id:
                plaintext_token:
                created_by_email:
                created_by_type:
                created_by_label:
  "/api/v3/admin/categories":
    get:
      summary: List categories
      tags:
      - Categories
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a paginated list of the store's categories (manual hierarchical taxons; rule-based collections are excluded).

        **Required scope:** `read_categories` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: categories } = await client.categories.list({
            name_cont: 'Shirts',
            limit: 25,
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /categories -d '{"name_cont":"Shirts","limit":25}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of name and pretty name (partial, case-insensitive).
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., children, parent,
          ancestors).
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `automatic` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
          | `children_count` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `depth` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `parent_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `permalink` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `pretty_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `products_count` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[parent_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |

          </Accordion>

          **Sort by:** `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Category
        sortable:
        - automatic
        - children_count
        - created_at
        - depth
        - id
        - name
        - parent_id
        - permalink
        - position
        - pretty_name
        - products_count
        - updated_at
      responses:
        '200':
          description: categories found
          content:
            application/json:
              example:
                data:
                - id: ctg_UkLWZg9DAJ
                  name: Clothing
                  permalink: clothing
                  position: 0
                  depth: 0
                  meta_title:
                  meta_description:
                  meta_keywords:
                  children_count: 0
                  parent_id:
                  description: ''
                  description_html: ''
                  image_url:
                  square_image_url:
                  is_root: true
                  is_child: false
                  is_leaf: true
                  external_references: {}
                  metadata: {}
                  pretty_name: Clothing
                  lft: 1
                  rgt: 2
                  products_count: 0
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                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/Category"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
    post:
      summary: Create a category
      tags:
      - Categories
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Creates a category. Nests under the parent when parent_id is given, otherwise creates a top-level category.

        **Required scope:** `write_categories` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const category = await client.categories.create({
            name: 'Shirts',
            parent_id: 'ctg_UkLWZg9DAJ',
            description: '<p>Casual and dress shirts.</p>',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /categories -d '{"name":"Shirts","parent_id":"ctg_UkLWZg9DAJ","description":"<p>Casual
          and dress shirts.</p>"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '201':
          description: category created
          content:
            application/json:
              example:
                id: ctg_gbHJdmfrXB
                name: Shirts
                permalink: clothing/shirts
                position: 0
                depth: 1
                meta_title:
                meta_description:
                meta_keywords:
                children_count: 0
                parent_id: ctg_UkLWZg9DAJ
                description: ''
                description_html: ''
                image_url:
                square_image_url:
                is_root: false
                is_child: true
                is_leaf: true
                external_references: {}
                metadata: {}
                pretty_name: Clothing -> Shirts
                lft: 2
                rgt: 3
                products_count: 0
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/Category"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Name can't be blank
                  details:
                    name:
                    - code: blank
                      message: can't be blank
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CategoryCreateParams"
        required: true
  "/api/v3/admin/categories/{id}":
    get:
      summary: Get a category
      tags:
      - Categories
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a single category by ID.

        **Required scope:** `read_categories` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const category = await client.categories.get('ctg_UkLWZg9DAJ', {
            expand: ['children', 'ancestors'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /categories/{id} -d '{"expand":["children","ancestors"]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Category ID
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., children, parent,
          ancestors).
        schema:
          type: string
      responses:
        '200':
          description: category found
          content:
            application/json:
              example:
                id: ctg_UkLWZg9DAJ
                name: Clothing
                permalink: clothing
                position: 0
                depth: 0
                meta_title:
                meta_description:
                meta_keywords:
                children_count: 0
                parent_id:
                description: ''
                description_html: ''
                image_url:
                square_image_url:
                is_root: true
                is_child: false
                is_leaf: true
                external_references: {}
                metadata: {}
                pretty_name: Clothing
                lft: 1
                rgt: 2
                products_count: 0
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/Category"
        '404':
          description: category not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Category not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update a category
      tags:
      - Categories
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Updates a category.

        **Required scope:** `write_categories` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const category = await client.categories.update('ctg_UkLWZg9DAJ', {
            name: 'Apparel',
            meta_title: 'Apparel for every season',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /categories/{id} -d '{"name":"Apparel","meta_title":"Apparel
          for every season"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Category ID
        schema:
          type: string
      responses:
        '200':
          description: category updated
          content:
            application/json:
              example:
                id: ctg_UkLWZg9DAJ
                name: Apparel
                permalink: clothing
                position: 0
                depth: 0
                meta_title:
                meta_description:
                meta_keywords:
                children_count: 0
                parent_id:
                description: ''
                description_html: ''
                image_url:
                square_image_url:
                is_root: true
                is_child: false
                is_leaf: true
                external_references: {}
                metadata: {}
                pretty_name: Apparel
                lft: 1
                rgt: 2
                products_count: 0
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/Category"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CategoryUpdateParams"
        required: true
    delete:
      summary: Delete a category
      tags:
      - Categories
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Deletes a category and its descendants.

        **Required scope:** `write_categories` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.categories.delete('ctg_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /categories/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Category ID
        schema:
          type: string
      responses:
        '204':
          description: category deleted
  "/api/v3/admin/categories/{id}/reposition":
    patch:
      summary: Reposition a category
      tags:
      - Categories
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Moves a category to a new parent and/or index within the tree.

        **Required scope:** `write_categories` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Moves the category under a new parent, as its first child.
          const category = await client.categories.reposition('ctg_gbHJdmfrXB', {
            new_parent_id: 'ctg_UkLWZg9DAJ',
            new_position: 0,
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /categories/{id}/reposition -d '{"new_parent_id":"ctg_UkLWZg9DAJ","new_position":0}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Category ID
        schema:
          type: string
      responses:
        '200':
          description: category repositioned
          content:
            application/json:
              example:
                id: ctg_gbHJdmfrXB
                name: Footwear
                permalink: clothing/footwear
                position: 0
                depth: 1
                meta_title:
                meta_description:
                meta_keywords:
                children_count: 0
                parent_id: ctg_UkLWZg9DAJ
                description: ''
                description_html: ''
                image_url:
                square_image_url:
                is_root: false
                is_child: true
                is_leaf: true
                external_references: {}
                metadata: {}
                pretty_name: Clothing -> Footwear
                lft: 2
                rgt: 3
                products_count: 0
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/Category"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CategoryRepositionParams"
        required: true
  "/api/v3/admin/categories/{category_id}/products":
    get:
      summary: List category products
      tags:
      - Categories
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Products classified under the category, ordered by their classification position.

        **Required scope:** `read_categories` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: products } = await client.categories.products.list('ctg_UkLWZg9DAJ', {
            limit: 25,
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /categories/{category_id}/products -d '{"limit":25}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: category_id
        in: path
        required: true
        description: Category ID
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches product name or variant SKU (partial, case-insensitive),
          and the store's searchable custom fields.
      - name: q[ascend_by_price]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `ascend_by_price`.
      - name: q[descend_by_price]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `descend_by_price`.
      - name: q[in_categories][]
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        description: Applies `in_categories` to the given value.
      - name: q[in_category]
        in: query
        required: false
        schema:
          type: string
        description: Applies `in_category` to the given value.
      - name: q[in_collection]
        in: query
        required: false
        schema:
          type: string
        description: Applies `in_collection` to the given value.
      - name: q[in_stock]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `in_stock`.
      - name: q[in_taxon]
        in: query
        required: false
        schema:
          type: string
        description: Applies `in_taxon` to the given value.
      - name: q[not_discontinued]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `not_discontinued`.
      - name: q[out_of_stock]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `out_of_stock`.
      - name: q[price_between][]
        in: query
        required: false
        schema:
          type: array
          items:
            type: number
          minItems: 2
          maxItems: 2
        description: Applies `price_between` to the given value.
      - name: q[price_gte]
        in: query
        required: false
        schema:
          type: number
        description: Applies `price_gte` to the given value.
      - name: q[price_lte]
        in: query
        required: false
        schema:
          type: number
        description: Applies `price_lte` to the given value.
      - name: q[search_by_name]
        in: query
        required: false
        schema:
          type: string
        description: Applies `search_by_name` to the given value.
      - name: q[with_option_value_ids][]
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        description: Applies `with_option_value_ids` to the given value.
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `available_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `description` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `slug` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `status` | One of `draft`, `active`, `archived`, `proposed`, `rejected` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[categories_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |
          | `categories_parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |
          | `channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
          | `collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |
          | `default_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |
          | `default_variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
          | `default_variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
          | `default_variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `default_variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
          | `labels_` | `created_at`, `id`, `name`, `updated_at` |
          | `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |
          | `product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |
          | `product_type_` | `created_at`, `id`, `name`, `updated_at` |
          | `product_type_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |
          | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `store_` | `created_at`, `id`, `name`, `updated_at` |
          | `tags_` | `created_at`, `id`, `name`, `updated_at` |
          | `variants_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |
          | `variants_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
          | `variants_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
          | `variants_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `variants_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |

          </Accordion>

          **Sort by:** `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Product
        sortable:
        - available_on
        - created_at
        - description
        - discontinue_on
        - id
        - name
        - price
        - seller_id
        - slug
        - status
        - updated_at
      responses:
        '200':
          description: products found
          content:
            application/json:
              example:
                data: []
                meta:
                  page: 1
                  limit: 25
                  count: 0
                  pages: 1
                  from: 0
                  to: 0
                  in: 0
                  previous:
                  next:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Product"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
    post:
      summary: Add products to a category
      tags:
      - Categories
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Classifies products under the category in bulk (appended to the end). Already-classified products are skipped; the count reports what was added.

        **Required scope:** `write_categories` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { added_count } = await client.categories.products.create('ctg_UkLWZg9DAJ', [
            'prod_UkLWZg9DAJ',
            'prod_9XbR2kQwLm',
          ])
      - lang: bash
        label: Spree CLI
        source: spree api post /categories/{category_id}/products -d '{ ... }'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: category_id
        in: path
        required: true
        description: Category ID
        schema:
          type: string
      responses:
        '201':
          description: products added
          content:
            application/json:
              example:
                added_count: 1
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProductMembershipParams"
        required: true
    delete:
      summary: Remove products from a category
      tags:
      - Categories
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Removes products from the category's manual classification in bulk. Ids that are not classified are ignored; the count reports what was removed.

        **Required scope:** `write_categories` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { removed_count } = await client.categories.products.delete('ctg_UkLWZg9DAJ', [
            'prod_UkLWZg9DAJ',
          ])
      - lang: bash
        label: Spree CLI
        source: spree api delete /categories/{category_id}/products
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: category_id
        in: path
        required: true
        description: Category ID
        schema:
          type: string
      responses:
        '200':
          description: products removed
          content:
            application/json:
              example:
                removed_count: 1
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProductMembershipParams"
        required: true
  "/api/v3/admin/categories/{category_id}/products/{id}/reposition":
    patch:
      summary: Reposition a category product
      tags:
      - Categories
      operationId: categories_reposition_product
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Moves a product to a new index among the category's products.

        **Required scope:** `write_categories` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Moves the product to the top of the category; positions are 0-based.
          await client.categories.products.reposition('ctg_UkLWZg9DAJ', 'prod_UkLWZg9DAJ', {
            new_position: 0,
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /categories/{category_id}/products/{id}/reposition
          -d '{"new_position":0}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: category_id
        in: path
        required: true
        description: Category ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Product ID
        schema:
          type: string
      responses:
        '204':
          description: product repositioned
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProductMembershipRepositionParams"
        required: true
  "/api/v3/admin/categories/{category_id}/custom_fields":
    get:
      summary: List category custom fields
      tags:
      - Categories
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the category's custom field values.

        **Required scope:** `read_categories` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: customFields } = await client.categories.customFields.list('ctg_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /categories/{category_id}/custom_fields
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: category_id
        in: path
        required: true
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., custom_field_definition).
          Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., key,value,namespace).
          id is always included.
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: CustomField
        sortable:
        - created_at
        - id
        - updated_at
      responses:
        '200':
          description: custom fields found
          content:
            application/json:
              example:
                data:
                - id: cf_UkLWZg9DAJ
                  label: Title
                  field_type: short_text
                  key: custom.title
                  value: wool
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  storefront_visible: true
                  custom_field_definition_id: cfdef_UkLWZg9DAJ
                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/CustomField"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
  "/api/v3/admin/channels":
    get:
      summary: List channels
      tags:
      - Channels
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the channels configured for the current store.

        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: channels } = await client.channels.list()
      - lang: bash
        label: Spree CLI
        source: spree api get /channels
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of name (partial, case-insensitive).
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
          | `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `default` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `store_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Channel
        sortable:
        - active
        - code
        - created_at
        - default
        - id
        - name
        - store_id
        - updated_at
      responses:
        '200':
          description: channels found
          content:
            application/json:
              example:
                data:
                - id: ch_UkLWZg9DAJ
                  name: Online Store
                  code: online
                  active: true
                  default: true
                  storefront_access:
                  guest_checkout:
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  order_routing_strategy:
                  stock_location_ids: []
                  default_catalog_id:
                - id: ch_gbHJdmfrXB
                  name: Wholesale
                  code: wholesale
                  active: true
                  default: false
                  storefront_access:
                  guest_checkout:
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  order_routing_strategy:
                  stock_location_ids: []
                  default_catalog_id:
                meta:
                  page: 1
                  limit: 25
                  count: 2
                  pages: 1
                  from: 1
                  to: 2
                  in: 2
                  previous:
                  next:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Channel"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
    post:
      summary: Create a channel
      tags:
      - Channels
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Creates a new channel on the current store. `code` is normalized to a
        URL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's
        derived from `name`.


        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // `code` is optional — when omitted it's derived from `name`
          // ("Point of Sale" → "point-of-sale").
          const channel = await client.channels.create({
            name: 'Point of Sale',
            code: 'pos',
            active: true,
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /channels -d '{"name":"Point of Sale","code":"pos","active":true}'
      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: channel created
          content:
            application/json:
              example:
                id: ch_EfhxLZ9ck8
                name: Marketplace
                code: marketplace
                active: true
                default: false
                storefront_access:
                guest_checkout:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                order_routing_strategy:
                stock_location_ids: []
                default_catalog_id:
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ChannelCreateParams"
        required: true
  "/api/v3/admin/channels/{id}":
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      summary: Get a channel
      tags:
      - Channels
      security:
      - api_key: []
        bearer_auth: []
      description: "**Required scope:** `read_settings` (for API-key authentication)."
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const channel = await client.channels.get('channel_xxx')
      - lang: bash
        label: Spree CLI
        source: spree api get /channels/{id}
      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: channel found
          content:
            application/json:
              example:
                id: ch_gbHJdmfrXB
                name: Wholesale
                code: wholesale
                active: true
                default: false
                storefront_access:
                guest_checkout:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                order_routing_strategy:
                stock_location_ids: []
                default_catalog_id:
    patch:
      summary: Update a channel
      tags:
      - Channels
      security:
      - api_key: []
        bearer_auth: []
      description: "**Required scope:** `write_settings` (for API-key authentication)."
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const channel = await client.channels.update('channel_xxx', {
            name: 'Wholesale (Updated)',
            active: false,
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /channels/{id} -d '{"name":"Wholesale (Updated)","active":false}'
      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: channel updated
          content:
            application/json:
              example:
                id: ch_gbHJdmfrXB
                name: Wholesale (Updated)
                code: wholesale
                active: true
                default: false
                storefront_access: login_required
                guest_checkout: false
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                order_routing_strategy:
                stock_location_ids: []
                default_catalog_id:
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ChannelUpdateParams"
        required: true
    delete:
      summary: Delete a channel
      tags:
      - Channels
      security:
      - api_key: []
        bearer_auth: []
      description: "**Required scope:** `write_settings` (for API-key authentication)."
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.channels.delete('channel_xxx')
      - lang: bash
        label: Spree CLI
        source: spree api delete /channels/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '204':
          description: channel deleted
  "/api/v3/admin/channels/{id}/add_products":
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    post:
      summary: Publish products on a channel
      tags:
      - Channels
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Publishes the listed products on this channel. Idempotent — re-publishing
        an already-published product updates its publication window. Products from
        sibling stores are silently dropped.


        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Idempotent — re-publishing an already-published product updates its
          // publication window. `published_at`/`unpublished_at` are optional:
          // `null` (or omitted) means live immediately and never come down.
          const { product_count } = await client.channels.addProducts('channel_xxx', {
            product_ids: ['prod_xxx', 'prod_yyy'],
            published_at: '2026-07-01T00:00:00Z',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /channels/{id}/add_products -d '{"product_ids":["prod_xxx","prod_yyy"],"published_at":"2026-07-01T00:00:00Z"}'
      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: products published
          content:
            application/json:
              example:
                product_count: 1
              schema:
                type: object
                properties:
                  product_count:
                    type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ChannelAddProductsParams"
        required: true
  "/api/v3/admin/channels/{id}/remove_products":
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    post:
      summary: Unpublish products from a channel
      tags:
      - Channels
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Unpublishes the listed products from this channel.

        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { product_count } = await client.channels.removeProducts('channel_xxx', {
            product_ids: ['prod_xxx', 'prod_yyy'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /channels/{id}/remove_products -d '{"product_ids":["prod_xxx","prod_yyy"]}'
      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: products unpublished
          content:
            application/json:
              example:
                product_count: 1
              schema:
                type: object
                properties:
                  product_count:
                    type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ChannelRemoveProductsParams"
        required: true
  "/api/v3/admin/channels/{channel_id}/order_routing_rules":
    parameters:
    - name: channel_id
      in: path
      required: true
      schema:
        type: string
    get:
      summary: List order routing rules for a channel
      tags:
      - Channels
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the channel's routing rules in priority order. The rules engine walks them top-down; see the Order Routing guide.

        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: rules } = await client.channels.orderRoutingRules.list('ch_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /channels/{channel_id}/order_routing_rules
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[active_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
          | `channel_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `store_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `active`, `channel_id`, `created_at`, `id`, `position`, `store_id`, `type`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: OrderRoutingRule
        sortable:
        - active
        - channel_id
        - created_at
        - id
        - position
        - store_id
        - type
        - updated_at
      responses:
        '200':
          description: rules found
          content:
            application/json:
              example:
                data:
                - id: orule_UkLWZg9DAJ
                  position: 1
                  active: true
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  type: preferred_location
                  channel_id: ch_UkLWZg9DAJ
                  preferences: {}
                - id: orule_gbHJdmfrXB
                  position: 2
                  active: true
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  type: minimize_splits
                  channel_id: ch_UkLWZg9DAJ
                  preferences: {}
                - id: orule_EfhxLZ9ck8
                  position: 3
                  active: true
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  type: default_location
                  channel_id: ch_UkLWZg9DAJ
                  preferences: {}
                meta:
                  page: 1
                  limit: 25
                  count: 3
                  pages: 1
                  from: 1
                  to: 3
                  in: 3
                  previous:
                  next:
    post:
      summary: Create an order routing rule on a channel
      tags:
      - Channels
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Adds a rule to the channel's routing list. The `type` is the wire shorthand from `GET /order_routing_rules/types` (e.g. `preferred_location`). Omitting `position` appends the rule at the end of the list. Each rule kind can appear at most once per channel — a duplicate `type` is rejected with a validation error.

        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const rule = await client.channels.orderRoutingRules.create('ch_UkLWZg9DAJ', {
            type: 'preferred_location',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /channels/{channel_id}/order_routing_rules -d '{"type":"preferred_location"}'
      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: rule created
          content:
            application/json:
              example:
                id: orule_VqXmZF31wY
                position: 3
                active: true
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                type: default_location
                channel_id: ch_UkLWZg9DAJ
                preferences: {}
        '422':
          description: unknown rule type
          content:
            application/json:
              example:
                error:
                  code: unknown_order_routing_rule_type
                  message: Unknown type
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/OrderRoutingRuleCreateParams"
        required: true
  "/api/v3/admin/channels/{channel_id}/order_routing_rules/{id}":
    parameters:
    - name: channel_id
      in: path
      required: true
      schema:
        type: string
    - name: id
      in: path
      required: true
      schema:
        type: string
    patch:
      summary: Update an order routing rule
      tags:
      - Channels
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Updates a rule's `active` flag, `position` (the list reorders around it), or `preferences`. The rule kind cannot be changed — delete and re-create instead.

        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const rule = await client.channels.orderRoutingRules.update('ch_UkLWZg9DAJ', 'orule_k5nR8xLq', {
            active: false,
            position: 2,
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /channels/{channel_id}/order_routing_rules/{id} -d
          '{"active":false,"position":2}'
      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: rule updated
          content:
            application/json:
              example:
                id: orule_UkLWZg9DAJ
                position: 2
                active: false
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                type: preferred_location
                channel_id: ch_UkLWZg9DAJ
                preferences: {}
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/OrderRoutingRuleUpdateParams"
        required: true
    delete:
      summary: Delete an order routing rule
      tags:
      - Channels
      security:
      - api_key: []
        bearer_auth: []
      description: "**Required scope:** `write_settings` (for API-key authentication)."
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.channels.orderRoutingRules.delete('ch_UkLWZg9DAJ', 'orule_k5nR8xLq')
      - lang: bash
        label: Spree CLI
        source: spree api delete /channels/{channel_id}/order_routing_rules/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '204':
          description: rule deleted
  "/api/v3/admin/order_routing_rules/types":
    get:
      summary: List available order routing rule types
      tags:
      - Channels
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Enumerates the registered rule kinds with their labels, descriptions and preference schemas — drives the "Add rule" picker in the admin dashboard. Plugins extend the list by registering `Spree::OrderRoutingRule` subclasses via `Spree.order_routing.rules`.

        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: ruleTypes } = await client.orderRoutingRules.types()
      - lang: bash
        label: Spree CLI
        source: spree api get /order_routing_rules/types
      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: types found
          content:
            application/json:
              example:
                data:
                - type: default_location
                  label: Default location
                  description: Prefer the stock location marked as default
                  schema:
                    type: object
                    properties: {}
                    additionalProperties: false
                - type: minimize_splits
                  label: Minimize splits
                  description: Prefer the location that can fulfill the most items
                    on its own, avoiding split shipments
                  schema:
                    type: object
                    properties: {}
                    additionalProperties: false
                - type: preferred_location
                  label: Preferred location
                  description: Fulfill from the location pinned on the order, when
                    one is set
                  schema:
                    type: object
                    properties: {}
                    additionalProperties: false
  "/api/v3/admin/custom_field_definitions":
    get:
      summary: List custom field definitions
      tags:
      - Custom Fields
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns all defined custom fields. Filter by `?q[resource_type_eq]=product` to narrow to one parent type.

        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: definitions } = await client.customFieldDefinitions.list({
            resource_type_eq: 'product',
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /custom_field_definitions -d '{"resource_type_eq":"product"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of namespace, key, and label (partial, case-insensitive).
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand. Use dot notation for
          nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., key,label,field_type).
          id is always included.
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[key_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `field_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `key` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `label` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `namespace` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `resource_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `searchable` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
          | `sortable` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
          | `storefront_visible` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `field_type`, `id`, `key`, `label`, `namespace`, `resource_type`, `searchable`, `sortable`, `storefront_visible`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: CustomFieldDefinition
        sortable:
        - created_at
        - field_type
        - id
        - key
        - label
        - namespace
        - resource_type
        - searchable
        - sortable
        - storefront_visible
        - updated_at
      responses:
        '200':
          description: definitions returned
          content:
            application/json:
              example:
                data:
                - id: cfdef_UkLWZg9DAJ
                  namespace: specs
                  key: fabric
                  label: Title
                  field_type: short_text
                  storefront_visible: true
                  searchable: false
                  sortable: false
                  filter_key: cf_specs_fabric
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  resource_type: product
                - id: cfdef_gbHJdmfrXB
                  namespace: custom
                  key: order_notes
                  label: Order Notes
                  field_type: short_text
                  storefront_visible: true
                  searchable: false
                  sortable: false
                  filter_key: cf_custom_order_notes
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  resource_type: order
                meta:
                  page: 1
                  limit: 25
                  count: 2
                  pages: 1
                  from: 1
                  to: 2
                  in: 2
                  previous:
                  next:
    post:
      summary: Create a custom field definition
      tags:
      - Custom Fields
      security:
      - api_key: []
        bearer_auth: []
      description: "**Required scope:** `write_settings` (for API-key authentication)."
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const definition = await client.customFieldDefinitions.create({
            namespace: 'specs',
            key: 'origin',
            label: 'Country of Origin',
            field_type: 'short_text',
            resource_type: 'product',
            storefront_visible: true,
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /custom_field_definitions -d '{"namespace":"specs","key":"origin","label":"Country
          of Origin","field_type":"short_text","resource_type":"product","storefront_visible":true}'
      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: definition created
          content:
            application/json:
              example:
                id: cfdef_EfhxLZ9ck8
                namespace: specs
                key: origin
                label: Country of Origin
                field_type: short_text
                storefront_visible: true
                searchable: false
                sortable: false
                filter_key: cf_specs_origin
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                resource_type: product
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CustomFieldDefinitionCreateParams"
        required: true
  "/api/v3/admin/custom_field_definitions/{id}":
    get:
      summary: Show a custom field definition
      tags:
      - Custom Fields
      security:
      - api_key: []
        bearer_auth: []
      description: "**Required scope:** `read_settings` (for API-key authentication)."
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const definition = await client.customFieldDefinitions.get('cfd_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /custom_field_definitions/{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
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand. Use dot notation for
          nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., key,label,field_type).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: definition found
          content:
            application/json:
              example:
                id: cfdef_UkLWZg9DAJ
                namespace: specs
                key: fabric
                label: Title
                field_type: short_text
                storefront_visible: true
                searchable: false
                sortable: false
                filter_key: cf_specs_fabric
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                resource_type: product
    patch:
      summary: Update a custom field definition
      tags:
      - Custom Fields
      security:
      - api_key: []
        bearer_auth: []
      description: "**Required scope:** `write_settings` (for API-key authentication)."
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const definition = await client.customFieldDefinitions.update('cfd_UkLWZg9DAJ', {
            label: 'Country of Origin',
            storefront_visible: false,
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /custom_field_definitions/{id} -d '{"label":"Country
          of Origin","storefront_visible":false}'
      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: definition updated
          content:
            application/json:
              example:
                id: cfdef_UkLWZg9DAJ
                namespace: specs
                key: fabric
                label: Fabric Composition
                field_type: short_text
                storefront_visible: false
                searchable: false
                sortable: false
                filter_key: cf_specs_fabric
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                resource_type: product
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CustomFieldDefinitionUpdateParams"
        required: true
    delete:
      summary: Delete a custom field definition
      tags:
      - Custom Fields
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Deletes the definition and cascades to all custom field values referencing it.

        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.customFieldDefinitions.delete('cfd_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /custom_field_definitions/{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
        schema:
          type: string
      responses:
        '204':
          description: definition deleted
  "/api/v3/admin/customer_groups":
    get:
      summary: List customer groups
      tags:
      - Customer Groups
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the customer groups configured for the current store. Groups
        segment customers for targeted promotions (see the `customer_group`
        promotion rule) and reporting. The list endpoint never embeds the
        member list — fetch a single group with `?expand=customers` if you
        need them inline, or query `/admin/customers?customer_group_id_in=…`
        for paginated membership.


        **Required scope:** `read_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: groups } = await client.customerGroups.list({ page: 1, limit: 25 })
      - lang: bash
        label: Spree CLI
        source: spree api get /customer_groups -d '{"page":1,"limit":25}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of name (partial, case-insensitive).
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      - name: sort
        in: query
        required: false
        description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include. id is always included.
        schema:
          type: string
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: CustomerGroup
        sortable:
        - created_at
        - id
        - name
        - updated_at
      responses:
        '200':
          description: customer groups found
          content:
            application/json:
              example:
                data:
                - id: cg_UkLWZg9DAJ
                  name: VIPs
                  description: Top spenders
                  customers_count: 0
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                - id: cg_gbHJdmfrXB
                  name: Wholesale
                  description:
                  customers_count: 0
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                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/CustomerGroup"
                  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"
    post:
      summary: Create a customer group
      tags:
      - Customer Groups
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Creates a customer group in the current store. `customer_ids` is
        optional; when present, customers are attached at create time.
        Pass prefixed IDs (e.g. `cus_…`) — the server decodes them
        automatically.


        **Required scope:** `write_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const group = await client.customerGroups.create({
            name: 'VIP customers',
            description: 'Top spenders, eligible for early access',
            customer_ids: ['cus_UkLWZg9DAJ', 'cus_QrLWXg9CAJ'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /customer_groups -d '{"name":"VIP customers","description":"Top
          spenders, eligible for early access","customer_ids":["cus_UkLWZg9DAJ","cus_QrLWXg9CAJ"]}'
      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: customer group created
          content:
            application/json:
              example:
                id: cg_EfhxLZ9ck8
                name: Wholesale 2
                description: B2B accounts
                customers_count: 1
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/CustomerGroup"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Name can't be blank
                  details:
                    name:
                    - code: blank
                      message: can't be blank
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CustomerGroupCreateParams"
        required: true
  "/api/v3/admin/customer_groups/{id}":
    parameters:
    - name: id
      in: path
      required: true
      description: Customer group prefixed ID
      schema:
        type: string
    get:
      summary: Get a customer group
      tags:
      - Customer Groups
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a single customer group. Pass `?expand=customers` to embed
        the full member list inline (recommended only for single-record
        reads — embed cost scales with membership size).


        **Required scope:** `read_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Pass `expand: ['customers']` to embed the group's customers in the response
          // — omit it for the much smaller index-payload shape.
          const group = await client.customerGroups.get('cg_UkLWZg9DAJ', { expand: ['customers'] })
      - lang: bash
        label: Spree CLI
        source: spree api get /customer_groups/{id} -d '{"expand":["customers"]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: 'Comma-separated associations to embed. Supported: `customers`.'
        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: customer group with embedded customers
          content:
            application/json:
              example:
                id: cg_UkLWZg9DAJ
                name: VIPs
                description: Top spenders
                customers_count: 1
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                customers:
                - id: cust_UkLWZg9DAJ
                  email: [email protected]
                  first_name: Dan
                  last_name: Ebert
                  phone:
                  accepts_email_marketing: false
                  email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
                  full_name: Dan Ebert
                  available_store_credit_total: '0.00'
                  failed_attempts: 0
                  metadata: {}
                  email_marketing_consent_source: unknown
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  anonymized_at:
                  anonymized: false
                  tags: []
                  internal_note:
                  internal_note_html:
                  default_billing_address_id:
                  default_shipping_address_id:
                  orders_count: 0
                  total_spent: '0.00'
                  last_order_completed_at:
                  customer_group_ids:
                  - cg_UkLWZg9DAJ
              schema:
                "$ref": "#/components/schemas/CustomerGroup"
        '404':
          description: customer group not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Customer group not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update a customer group
      tags:
      - Customer Groups
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Updates name, description, or membership. `customer_ids` is a
        full-set replacement — the server reconciles the membership to
        match the array, adding new IDs and removing ones not present.
        Send `customer_ids: []` to clear all members.


        **Required scope:** `write_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // `customer_ids` is a full-set update — the model reconciles the membership
          // to match the array (adds new IDs, removes ones not present).
          const group = await client.customerGroups.update('cg_UkLWZg9DAJ', {
            name: 'VIP customers (Q1)',
            customer_ids: ['cus_UkLWZg9DAJ'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /customer_groups/{id} -d '{"name":"VIP customers (Q1)","customer_ids":["cus_UkLWZg9DAJ"]}'
      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: customer group updated
          content:
            application/json:
              example:
                id: cg_UkLWZg9DAJ
                name: VIP customers (Q1)
                description: Top spenders
                customers_count: 0
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/CustomerGroup"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Name can't be blank
                  details:
                    name:
                    - code: blank
                      message: can't be blank
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CustomerGroupUpdateParams"
        required: true
    delete:
      summary: Delete a customer group
      tags:
      - Customer Groups
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.

        **Required scope:** `write_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.customerGroups.delete('cg_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /customer_groups/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '204':
          description: customer group deleted
  "/api/v3/admin/customers/{customer_id}/custom_fields":
    get:
      summary: List customer custom fields
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the customer's custom field values.

        **Required scope:** `read_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: customFields } = await client.customers.customFields.list('cus_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /customers/{customer_id}/custom_fields
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., custom_field_definition).
          Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., key,value,namespace).
          id is always included.
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: CustomField
        sortable:
        - created_at
        - id
        - updated_at
      responses:
        '200':
          description: custom fields found
          content:
            application/json:
              example:
                data:
                - id: cf_UkLWZg9DAJ
                  label: Title
                  field_type: short_text
                  key: custom.title
                  value: wool
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  storefront_visible: true
                  custom_field_definition_id: cfdef_UkLWZg9DAJ
                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/CustomField"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
  "/api/v3/admin/customers/{id}/export":
    get:
      summary: Export a customer's personal data
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns everything the store holds about this customer, for answering a
        GDPR right-of-access request (Art. 15) that reached the merchant
        directly.


        **Required scope:** `read_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Everything the store holds about the customer, to answer a GDPR access request:
          const customerData = await client.customers.export('cus_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /customers/{id}/export
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: customer data
          content:
            application/json:
              example:
                account:
                  id: cust_UkLWZg9DAJ
                  email: [email protected]
                  first_name: Jane
                  last_name: Doe
                  phone:
                  selected_locale:
                  tags: []
                  metadata:
                  internal_note:
                  created_at: '2026-01-15T12:00:00Z'
                  anonymized_at:
                marketing_consent:
                  accepts_email_marketing: false
                  consent_updated_at: '2026-01-15T12:00:00Z'
                  consent_source: unknown
                  newsletter_subscriptions: []
                consent_records: []
                addresses: []
                orders: []
                draft_orders: []
                order_groups: []
                carts: []
                payment_sources: []
                connected_logins: []
                store_credits: []
                gift_cards: []
                wishlists: []
                custom_fields: []
                companies: []
                tax_identifiers: []
                exported_at: '2026-01-15T12:00:00Z'
              schema:
                type: object
                properties:
                  account:
                    type: object
                  marketing_consent:
                    type: object
                  consent_records:
                    type: array
                    items:
                      type: object
                  addresses:
                    type: array
                    items:
                      type: object
                  orders:
                    type: array
                    items:
                      type: object
                  exported_at:
                    type: string
        '404':
          description: not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Customer not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/admin/customers/{id}/anonymize":
    post:
      x-spree-agent: false
      x-spree-agent-reason: Irreversible erasure of a person's data under GDPR Art.
        17, which is not something to offer a model behind one confirmation prompt.
      summary: Erase a customer's personal data
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Carries out a GDPR right-to-erasure request (Art. 17). Personal data is
        replaced across the account, its addresses, the address snapshots on
        past orders, saved cards, connected identities and live sessions.

        Orders, payments and tax records are kept — they carry their own
        retention obligation — with the personal details removed. The country,
        state and a truncated postal code survive on order addresses so the tax
        jurisdiction of a past sale stays provable.

        Irreversible.


        **Required scope:** `write_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Irreversible: personal data is erased, orders and payments are kept.
          const customer = await client.customers.anonymize('cus_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api post /customers/{id}/anonymize -d '{ ... }'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: customer anonymized
          content:
            application/json:
              example:
                id: cust_UkLWZg9DAJ
                email: anonymized-87c6bfa6-4803-420c-a5e2-b1c962f0f40a@invalid
                first_name: Redacted
                last_name: Redacted
                phone:
                accepts_email_marketing: false
                email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
                full_name: Redacted Redacted
                available_store_credit_total: '0.00'
                failed_attempts: 0
                metadata: {}
                email_marketing_consent_source: anonymization
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                anonymized_at: '2026-01-15T12:00:00Z'
                anonymized: true
                tags: []
                internal_note:
                internal_note_html:
                default_billing_address_id:
                default_shipping_address_id:
                orders_count: 0
                total_spent: '0.00'
                last_order_completed_at:
                customer_group_ids: []
              schema:
                type: object
                properties:
                  id:
                    type: string
                  email:
                    type: string
                  anonymized:
                    type: boolean
                  anonymized_at:
                    type: string
                    nullable: true
  "/api/v3/admin/consent_records":
    get:
      summary: List consent records
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the consents customers gave or withdrew, newest first, as evidence of what each one agreed to and when.

        **Required scope:** `read_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: consentRecords } = await client.consentRecords.list({
            email_eq: '[email protected]',
            sort: '-recorded_at',
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /consent_records -d '{"email_eq":"[email protected]","sort":"-recorded_at"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[email_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `accepted` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `purpose` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `recorded_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `source` | One of `checkout`, `registration`, `account`, `admin`, `newsletter`, `anonymization`, `unknown`, `import`, `storefront` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `accepted`, `created_at`, `email`, `id`, `purpose`, `recorded_at`, `source`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: ConsentRecord
        sortable:
        - accepted
        - created_at
        - email
        - id
        - purpose
        - recorded_at
        - source
        - updated_at
      responses:
        '200':
          description: consent records found
          content:
            application/json:
              example:
                data:
                - id: consent_UkLWZg9DAJ
                  purpose: terms_of_service
                  source: registration
                  accepted: true
                  email: [email protected]
                  ip_address:
                  created_at: '2026-01-15T12:00:00.000Z'
                  recorded_at: '2026-01-15T12:00:00Z'
                  documents: []
                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/ConsentRecord"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
  "/api/v3/admin/data_requests":
    get:
      summary: List data requests
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the requests customers made to export or erase their personal data, newest first.

        **Required scope:** `read_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: dataRequests } = await client.dataRequests.list({
            kind_eq: 'erasure',
            sort: '-requested_at',
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /data_requests -d '{"kind_eq":"erasure","sort":"-requested_at"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: q[access]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `access`.
      - name: q[erasure]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `erasure`.
      - name: q[in_progress]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `in_progress`.
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `completed_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `kind` | One of `access`, `erasure` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `requested_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `status` | One of `awaiting_confirmation`, `pending`, `processing`, `completed`, `failed`, `lapsed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `completed_at`, `created_at`, `email`, `id`, `kind`, `number`, `requested_at`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: DataRequest
        sortable:
        - completed_at
        - created_at
        - email
        - id
        - kind
        - number
        - requested_at
        - status
        - updated_at
      responses:
        '200':
          description: data requests found
          content:
            application/json:
              example:
                data:
                - id: dsr_UkLWZg9DAJ
                  number: DSR1001
                  kind: access
                  status: pending
                  requested_at: '2026-01-15T12:00:00Z'
                  completed_at:
                  expires_at:
                  email: [email protected]
                  error_message:
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  customer_id: cust_UkLWZg9DAJ
                  requested_by_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/DataRequest"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
    post:
      summary: Record a data request
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Records a request a customer made to the merchant directly, to export
        or erase their personal data, and starts answering it. A request of the
        same kind already in progress for the customer is returned instead of a
        second one.


        **Required scope:** `write_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const dataRequest = await client.dataRequests.create({
            customer_id: 'cus_UkLWZg9DAJ',
            kind: 'access',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /data_requests -d '{"customer_id":"cus_UkLWZg9DAJ","kind":"access"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '202':
          description: data request recorded
          content:
            application/json:
              example:
                id: dsr_UkLWZg9DAJ
                number: DSR1001
                kind: access
                status: pending
                requested_at: '2026-01-15T12:00:00Z'
                completed_at:
                expires_at:
                email: [email protected]
                error_message:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                customer_id: cust_UkLWZg9DAJ
                requested_by_id: adm_UkLWZg9DAJ
              schema:
                "$ref": "#/components/schemas/DataRequest"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/DataRequestCreateParams"
        required: true
  "/api/v3/admin/customers/{customer_id}/addresses":
    get:
      summary: List customer addresses
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the customer's saved addresses.

        **Required scope:** `read_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: addresses } = await client.customers.addresses.list('cus_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /customers/{customer_id}/addresses
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., country, state).
          Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., first_name,last_name,address1,city).
          id is always included.
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[address1_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `address1` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `address2` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `city` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `company` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `country_code` | One of the `CountryCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `first_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `last_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `phone` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `postal_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Address
        sortable:
        - address1
        - address2
        - city
        - company
        - country_code
        - created_at
        - first_name
        - id
        - last_name
        - phone
        - postal_code
        - state_code
        - updated_at
      responses:
        '200':
          description: addresses found
          content:
            application/json:
              example:
                data:
                - id: addr_UkLWZg9DAJ
                  label:
                  first_name: John
                  last_name: Doe
                  full_name: John Doe
                  address1: 27 Lovely Street
                  address2: Northwest
                  postal_code: '10118'
                  city: New York
                  phone: 555-555-0199
                  company: Company
                  country_name: United States
                  country_code: US
                  state_text: NY
                  state_code: NY
                  quick_checkout: false
                  is_default_billing: false
                  is_default_shipping: false
                  state_name: New York
                  owner:
                    id: cust_UkLWZg9DAJ
                    type: customer
                    name:
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  latitude:
                  longitude:
                  customer_id: cust_UkLWZg9DAJ
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
    post:
      summary: Create a customer address
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.

        **Required scope:** `write_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const address = await client.customers.addresses.create('cus_UkLWZg9DAJ', {
            first_name: 'Jane',
            last_name: 'Doe',
            address1: '350 Fifth Avenue',
            city: 'New York',
            postal_code: '10118',
            country_code: 'US',
            state_code: 'NY',
            phone: '+1 212 555 1234',
            label: 'Office',
            is_default_shipping: true,
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /customers/{customer_id}/addresses -d '{"first_name":"Jane","last_name":"Doe","address1":"350
          Fifth Avenue","city":"New York","postal_code":"10118","country_code":"US","state_code":"NY","phone":"+1
          212 555 1234","label":"Office","is_default_shipping":true}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: address created
          content:
            application/json:
              example:
                id: addr_gbHJdmfrXB
                label: Office
                first_name: Jane
                last_name: Doe
                full_name: Jane Doe
                address1: 350 Fifth Avenue
                address2:
                postal_code: '10118'
                city: New York
                phone: "+12125551234"
                company:
                country_name: United States
                country_code: US
                state_text: NY
                state_code: NY
                quick_checkout: false
                is_default_billing: false
                is_default_shipping: false
                state_name: New York
                owner:
                  id: cust_UkLWZg9DAJ
                  type: customer
                  name:
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                latitude:
                longitude:
                customer_id: cust_UkLWZg9DAJ
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CustomerAddressCreateParams"
        required: true
  "/api/v3/admin/customers/{customer_id}/addresses/{id}":
    patch:
      summary: Update a customer address
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Updates a customer address.

        **Required scope:** `write_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const address = await client.customers.addresses.update('cus_UkLWZg9DAJ', 'addr_UkLWZg9DAJ', {
            city: 'Manhattan',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /customers/{customer_id}/addresses/{id} -d '{"city":"Manhattan"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: customer_id
        in: path
        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_UkLWZg9DAJ
                label:
                first_name: John
                last_name: Doe
                full_name: John Doe
                address1: 29 Lovely Street
                address2: Northwest
                postal_code: '10118'
                city: Manhattan
                phone: 555-555-0199
                company: Company
                country_name: United States
                country_code: US
                state_text: NY
                state_code: NY
                quick_checkout: false
                is_default_billing: false
                is_default_shipping: false
                state_name: New York
                owner:
                  id: cust_UkLWZg9DAJ
                  type: customer
                  name:
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                latitude:
                longitude:
                customer_id: cust_UkLWZg9DAJ
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CustomerAddressUpdateParams"
        required: true
    delete:
      summary: Delete a customer address
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Deletes the address. If it was a default, the customer loses that default (no auto-promotion).

        **Required scope:** `write_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.customers.addresses.delete('cus_UkLWZg9DAJ', 'addr_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /customers/{customer_id}/addresses/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: address deleted
  "/api/v3/admin/customers/{customer_id}/credit_cards":
    get:
      summary: List customer credit cards
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.

        **Required scope:** `read_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: cards } = await client.customers.creditCards.list('cus_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /customers/{customer_id}/credit_cards
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., payment_method).
          Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., brand,last4,month,year).
          id is always included.
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: CreditCard
        sortable:
        - created_at
        - id
        - name
        - updated_at
      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:
                  customer_id: cust_UkLWZg9DAJ
                  payment_method_id: pm_UkLWZg9DAJ
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
  "/api/v3/admin/customers/{customer_id}/credit_cards/{id}":
    get:
      summary: Show a customer credit card
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a saved credit card by ID.

        **Required scope:** `read_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const card = await client.customers.creditCards.get('cus_UkLWZg9DAJ', 'cc_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /customers/{customer_id}/credit_cards/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., payment_method).
          Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., brand,last4,month,year).
          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:
                customer_id: cust_UkLWZg9DAJ
                payment_method_id: pm_UkLWZg9DAJ
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
    delete:
      summary: Delete a customer credit card
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Deletes a saved credit card.

        **Required scope:** `write_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.customers.creditCards.delete('cus_UkLWZg9DAJ', 'cc_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /customers/{customer_id}/credit_cards/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: credit card deleted
  "/api/v3/admin/customers/{customer_id}/store_credits":
    get:
      summary: List customer store credits
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns store credits issued to the customer.

        **Required scope:** `read_store_credits` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: storeCredits } = await client.customers.storeCredits.list('cus_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /customers/{customer_id}/store_credits
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of memo (partial, case-insensitive).
      - name: q[from_gift_card]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `from_gift_card`.
      - name: q[outstanding]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `outstanding`.
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., store, created_by).
          Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., amount,amount_used,memo,currency).
          id is always included.
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[memo_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `created_by_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `currency` | One of the `CurrencyCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `customer_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `memo` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[customer_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
          | `customer_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `customer_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `customer_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |
          | `customer_orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
          | `customer_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `customer_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |
          | `customer_tags_` | `created_at`, `id`, `name`, `updated_at` |

          </Accordion>

          **Sort by:** `amount`, `created_at`, `created_by_id`, `currency`, `customer_id`, `id`, `memo`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: StoreCredit
        sortable:
        - amount
        - created_at
        - created_by_id
        - currency
        - customer_id
        - id
        - memo
        - updated_at
      responses:
        '200':
          description: store credits found
          content:
            application/json:
              example:
                data:
                - id: credit_UkLWZg9DAJ
                  amount: '50.00'
                  amount_used: '0.00'
                  amount_remaining: '50.00'
                  currency: USD
                  memo:
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  amount_authorized: '0.00'
                  outstanding: true
                  customer_id: cust_UkLWZg9DAJ
                  created_by_id: adm_UkLWZg9DAJ
                  created_by_type: admin_user
                  originator_type:
                  originator_id:
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
    post:
      summary: Issue a store credit to a customer
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        `created_by` is set automatically from the authenticated admin.

        **Required scope:** `write_store_credits` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const credit = await client.customers.storeCredits.create('cus_UkLWZg9DAJ', {
            amount: '25.00',
            currency: 'USD',
            memo: 'Goodwill credit',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /customers/{customer_id}/store_credits -d '{"amount":"25.00","currency":"USD","memo":"Goodwill
          credit"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: store credit created
          content:
            application/json:
              example:
                id: credit_gbHJdmfrXB
                amount: '25.00'
                amount_used: '0.00'
                amount_remaining: '25.00'
                currency: USD
                memo: Goodwill
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                amount_authorized: '0.00'
                outstanding: true
                customer_id: cust_UkLWZg9DAJ
                created_by_id: adm_gbHJdmfrXB
                created_by_type: admin_user
                originator_type:
                originator_id:
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CustomerStoreCreditCreateParams"
        required: true
  "/api/v3/admin/customers/{customer_id}/store_credits/{id}":
    patch:
      summary: Update a store credit
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Update memo / amount. The amount can only be changed if `amount_used == 0`.

        **Required scope:** `write_store_credits` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const credit = await client.customers.storeCredits.update('cus_UkLWZg9DAJ', 'sc_UkLWZg9DAJ', {
            memo: 'Reissued for damaged shipment',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /customers/{customer_id}/store_credits/{id} -d '{"memo":"Reissued
          for damaged shipment"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: store credit updated
          content:
            application/json:
              example:
                id: credit_UkLWZg9DAJ
                amount: '50.00'
                amount_used: '0.00'
                amount_remaining: '50.00'
                currency: USD
                memo: Updated
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                amount_authorized: '0.00'
                outstanding: true
                customer_id: cust_UkLWZg9DAJ
                created_by_id: adm_UkLWZg9DAJ
                created_by_type: admin_user
                originator_type:
                originator_id:
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CustomerStoreCreditUpdateParams"
        required: true
    delete:
      summary: Delete a store credit
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.

        **Required scope:** `write_store_credits` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.customers.storeCredits.delete('cus_UkLWZg9DAJ', 'sc_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /customers/{customer_id}/store_credits/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: store credit deleted
  "/api/v3/admin/customers/{customer_id}/tax_identifiers":
    get:
      summary: List customer tax registrations
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the customer's own tax registrations, one per kind.

        **Required scope:** `read_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: registrations } = await client.customers.taxIdentifiers.list('cus_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /customers/{customer_id}/tax_identifiers
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: TaxIdentifier
        sortable:
        - created_at
        - id
        - updated_at
      responses:
        '200':
          description: registrations found
          content:
            application/json:
              example:
                data:
                - id: txi_UkLWZg9DAJ
                  kind: eu_vat
                  value: DE100000016
                  validation_status:
                  validation_evidence:
                  source:
                  validated_at:
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  validatable: false
                  customer_id: cust_UkLWZg9DAJ
                  cart_id:
                  order_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/TaxIdentifier"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
  "/api/v3/admin/customers/{customer_id}/tax_identifiers/{id}":
    patch:
      summary: Update a customer tax registration
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Corrects a registration number. A changed number is checked again before it counts as verified.

        **Required scope:** `write_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const registration = await client.customers.taxIdentifiers.update(
            'cus_UkLWZg9DAJ',
            'txi_UkLWZg9DAJ',
            { value: 'DE123456789' },
          )
      - lang: bash
        label: Spree CLI
        source: spree api patch /customers/{customer_id}/tax_identifiers/{id} -d '{"value":"DE123456789"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: registration updated
          content:
            application/json:
              example:
                id: txi_UkLWZg9DAJ
                kind: eu_vat
                value: DE100000008
                validation_status:
                validation_evidence:
                source:
                validated_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                validatable: false
                customer_id: cust_UkLWZg9DAJ
                cart_id:
                order_id:
              schema:
                "$ref": "#/components/schemas/TaxIdentifier"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/TaxIdentifierUpdateParams"
        required: true
  "/api/v3/admin/customers/{customer_id}/tax_identifiers/{id}/validate":
    parameters:
    - name: x-spree-api-key
      in: header
      required: true
      schema:
        type: string
    - name: Authorization
      in: header
      required: true
      schema:
        type: string
    - name: customer_id
      in: path
      required: true
      schema:
        type: string
    - name: id
      in: path
      required: true
      schema:
        type: string
    post:
      summary: Re-check a customer tax registration
      tags:
      - Customers
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const registration = await client.customers.taxIdentifiers.validate(
            'cust_UkLWZg9DAJ',
            'txi_UkLWZg9DAJ',
          )
      - lang: bash
        label: Spree CLI
        source: spree api post /customers/{customer_id}/tax_identifiers/{id}/validate
          -d '{ ... }'
      operationId: customer_tax_identifiers_validate
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Asks the registry again. Manual because a registry answers only "valid now" — a number verified
        last year may have been deregistered since — and because a check that came back unavailable
        cannot otherwise be retried without editing the number.


        **Required scope:** `write_customers` (for API-key authentication).
      responses:
        '202':
          description: registry check queued
          content:
            application/json:
              example:
                id: txi_UkLWZg9DAJ
                kind: eu_vat
                value: DE100000032
                validation_status: pending
                validation_evidence:
                source:
                validated_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                validatable: true
                customer_id: cust_UkLWZg9DAJ
                cart_id:
                order_id:
              schema:
                "$ref": "#/components/schemas/TaxIdentifier"
        '422':
          description: no validator installed for this kind
          content:
            application/json:
              example:
                error:
                  code: tax_id_not_validatable
                  message: No registry validator is installed for tax identifier kind
                    'eu_vat'
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/admin/customers":
    get:
      summary: List customers
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a paginated list of customers. Supports Ransack search/filters.

        **Required scope:** `read_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: customers } = await client.customers.list({
            search: 'jane',
            sort: '-created_at',
            limit: 25,
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /customers -d '{"search":"jane","sort":"-created_at","limit":25}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches email, first name, last name or full name (partial, case-insensitive).
      - name: q[anonymized]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `anonymized`.
      - name: q[with_min_total_spent]
        in: query
        required: false
        schema:
          type: number
        description: Applies `with_min_total_spent` to the given value.
      - name: q[with_standing_for_company][]
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        description: Applies `with_standing_for_company` to the given value.
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., addresses, store_credits).
          Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., email,first_name,last_name).
          id is always included.
        schema:
          type: string
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[email_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `accepts_email_marketing` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `first_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `last_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `phone` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[addresses_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `customer_groups_` | `created_at`, `id`, `name`, `updated_at` |
          | `orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
          | `orders_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `orders_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
          | `orders_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
          | `orders_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
          | `orders_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
          | `orders_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
          | `orders_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `orders_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `orders_shipments_` | `created_at`, `id`, `number`, `updated_at` |
          | `orders_store_` | `created_at`, `id`, `name`, `updated_at` |
          | `orders_tags_` | `created_at`, `id`, `name`, `updated_at` |
          | `ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `spree_roles_` | `created_at`, `id`, `name`, `updated_at` |
          | `tags_` | `created_at`, `id`, `name`, `updated_at` |

          </Accordion>

          **Sort by:** `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Customer
        sortable:
        - accepts_email_marketing
        - created_at
        - email
        - first_name
        - id
        - last_name
        - phone
        - updated_at
      responses:
        '200':
          description: customers found
          content:
            application/json:
              example:
                data:
                - id: cust_UkLWZg9DAJ
                  email: [email protected]
                  first_name: Jane
                  last_name: Doe
                  phone:
                  accepts_email_marketing: false
                  email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
                  full_name: Jane Doe
                  available_store_credit_total: '0.00'
                  failed_attempts: 0
                  metadata: {}
                  email_marketing_consent_source: unknown
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  anonymized_at:
                  anonymized: false
                  tags: []
                  internal_note:
                  internal_note_html:
                  default_billing_address_id:
                  default_shipping_address_id:
                  orders_count: 0
                  total_spent: '0.00'
                  last_order_completed_at:
                  customer_group_ids: []
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
    post:
      summary: Create a customer
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Creates a customer. No welcome email is sent automatically.

        **Required scope:** `write_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const customer = await client.customers.create({
            email: '[email protected]',
            first_name: 'Jane',
            last_name: 'Doe',
            phone: '+1 212 555 1234',
            tags: ['wholesale'],
            accepts_email_marketing: true,
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /customers -d '{"email":"[email protected]","first_name":"Jane","last_name":"Doe","phone":"+1
          212 555 1234","tags":["wholesale"],"accepts_email_marketing":true}'
      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: customer created
          content:
            application/json:
              example:
                id: cust_gbHJdmfrXB
                email: [email protected]
                first_name: New
                last_name: Customer
                phone:
                accepts_email_marketing: false
                email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
                full_name: New Customer
                available_store_credit_total: '0.00'
                failed_attempts: 0
                metadata: {}
                email_marketing_consent_source: unknown
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                anonymized_at:
                anonymized: false
                tags: []
                internal_note:
                internal_note_html:
                default_billing_address_id:
                default_shipping_address_id:
                orders_count: 0
                total_spent: '0.00'
                last_order_completed_at:
                customer_group_ids: []
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CustomerCreateParams"
        required: true
  "/api/v3/admin/customers/{id}":
    get:
      summary: Show a customer
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).

        **Required scope:** `read_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const customer = await client.customers.get('cus_UkLWZg9DAJ', {
            expand: ['addresses', 'store_credits'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /customers/{id} -d '{"expand":["addresses","store_credits"]}'
      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: Customer ID
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: 'Comma-separated associations: addresses, orders, store_credits,
          default_billing_address, default_shipping_address'
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., email,first_name,last_name).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: customer found
          content:
            application/json:
              example:
                id: cust_UkLWZg9DAJ
                email: [email protected]
                first_name: Jane
                last_name: Doe
                phone:
                accepts_email_marketing: false
                email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
                full_name: Jane Doe
                available_store_credit_total: '0.00'
                failed_attempts: 0
                metadata: {}
                email_marketing_consent_source: unknown
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                anonymized_at:
                anonymized: false
                tags: []
                internal_note:
                internal_note_html:
                default_billing_address_id:
                default_shipping_address_id:
                orders_count: 0
                total_spent: '0.00'
                last_order_completed_at:
                customer_group_ids: []
    patch:
      summary: Update a customer
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Updates customer attributes. `tags` replaces the full set.

        **Required scope:** `write_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const customer = await client.customers.update('cus_UkLWZg9DAJ', {
            first_name: 'Updated',
            tags: ['wholesale', 'vip'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /customers/{id} -d '{"first_name":"Updated","tags":["wholesale","vip"]}'
      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: customer updated
          content:
            application/json:
              example:
                id: cust_UkLWZg9DAJ
                email: [email protected]
                first_name: Updated
                last_name: Doe
                phone:
                accepts_email_marketing: false
                email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
                full_name: Updated Doe
                available_store_credit_total: '0.00'
                failed_attempts: 0
                metadata: {}
                email_marketing_consent_source: unknown
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                anonymized_at:
                anonymized: false
                tags: []
                internal_note:
                internal_note_html:
                default_billing_address_id:
                default_shipping_address_id:
                orders_count: 0
                total_spent: '0.00'
                last_order_completed_at:
                customer_group_ids: []
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CustomerUpdateParams"
        required: true
    delete:
      summary: Delete a customer
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Deletes a customer. Returns 422 if the customer has any orders.

        **Required scope:** `write_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.customers.delete('cus_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /customers/{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
        schema:
          type: string
      responses:
        '204':
          description: customer deleted
  "/api/v3/admin/customers/bulk_add_to_groups":
    post:
      summary: Bulk-add customers to groups
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Attaches each customer in `ids` to every group in `customer_group_ids`.
        Idempotent — customers already in a group are skipped server-side.
        Groups from sibling stores are silently ignored. Returns counts of
        customers and groups that were processed (post store-scoping).


        **Required scope:** `write_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const result = await client.customers.bulkAddToGroups({
            ids: ['cus_UkLWZg9DAJ', 'cus_QrLWXg9CAJ'],
            customer_group_ids: ['cg_UkLWZg9DAJ'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /customers/bulk_add_to_groups -d '{"ids":["cus_UkLWZg9DAJ","cus_QrLWXg9CAJ"],"customer_group_ids":["cg_UkLWZg9DAJ"]}'
      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: customers added to groups
          content:
            application/json:
              example:
                customer_count: 1
                customer_group_count: 1
              schema:
                type: object
                properties:
                  customer_count:
                    type: integer
                  customer_group_count:
                    type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CustomerBulkGroupsParams"
        required: true
  "/api/v3/admin/customers/bulk_remove_from_groups":
    post:
      summary: Bulk-remove customers from groups
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Detaches each customer in `ids` from every group in `customer_group_ids`.
        No-op for non-members. Groups from sibling stores are silently ignored.


        **Required scope:** `write_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const result = await client.customers.bulkRemoveFromGroups({
            ids: ['cus_UkLWZg9DAJ'],
            customer_group_ids: ['cg_UkLWZg9DAJ'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /customers/bulk_remove_from_groups -d '{"ids":["cus_UkLWZg9DAJ"],"customer_group_ids":["cg_UkLWZg9DAJ"]}'
      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: customers removed from groups
          content:
            application/json:
              example:
                customer_count: 1
                customer_group_count: 1
              schema:
                type: object
                properties:
                  customer_count:
                    type: integer
                  customer_group_count:
                    type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CustomerBulkGroupsParams"
        required: true
  "/api/v3/admin/customers/bulk_add_tags":
    post:
      summary: Bulk-add tags to customers
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Adds each tag name in `tags` to every customer in `ids`. Tags are
        upserted by name; re-adding an existing tag is a no-op.


        **Required scope:** `write_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const result = await client.customers.bulkAddTags({
            ids: ['cus_UkLWZg9DAJ', 'cus_QrLWXg9CAJ'],
            tags: ['vip', 'newsletter'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /customers/bulk_add_tags -d '{"ids":["cus_UkLWZg9DAJ","cus_QrLWXg9CAJ"],"tags":["vip","newsletter"]}'
      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: tags added
          content:
            application/json:
              example:
                customer_count: 1
                tag_count: 2
              schema:
                type: object
                properties:
                  customer_count:
                    type: integer
                  tag_count:
                    type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/BulkTagsParams"
        required: true
  "/api/v3/admin/customers/bulk_remove_tags":
    post:
      summary: Bulk-remove tags from customers
      tags:
      - Customers
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Removes each tag name in `tags` from every customer in `ids`. No-op
        for customers that don't carry the tag.


        **Required scope:** `write_customers` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const result = await client.customers.bulkRemoveTags({
            ids: ['cus_UkLWZg9DAJ'],
            tags: ['vip'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /customers/bulk_remove_tags -d '{"ids":["cus_UkLWZg9DAJ"],"tags":["vip"]}'
      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: tags removed
          content:
            application/json:
              example:
                customer_count: 1
                tag_count: 1
              schema:
                type: object
                properties:
                  customer_count:
                    type: integer
                  tag_count:
                    type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/BulkTagsParams"
        required: true
  "/api/v3/admin/email_templates":
    get:
      summary: List email templates
      tags:
      - Email Templates
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns every email template merchants may edit: the emails customers
        receive, the email layout and the shared partials. Each shows what
        customers receive now (the store's published version, else Spree's
        default) and any draft in progress. Staff emails are not editable.


        **Required scope:** `read_email_templates` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const templates = await client.emailTemplates.list()
      - lang: bash
        label: Spree CLI
        source: spree api get /email_templates
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: language
        in: query
        required: false
        description: A language code, or `any` (the default) for the version every
          language uses
        schema:
          type: string
      responses:
        '200':
          description: email templates found
          content:
            application/json:
              example:
                data:
                - id: spree.order_mailer.confirm_email
                  key: spree/order_mailer/confirm_email
                  subject: Order {{ order.number }} confirmed
                  body: "<mj-section><mj-column><mj-text>Thanks for your order, {{
                    order.customer_name }}!</mj-text></mj-column></mj-section>\n"
                  language: any
                  customized_languages: []
                  kind: email
                  customized: false
                  published_at:
                  default_subject: Order {{ order.number }} confirmed
                  default_body: "<mj-section><mj-column><mj-text>Thanks for your order,
                    {{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"
                  published_language:
                  default_changed: false
                  base_subject:
                  base_body:
                  draft:
                - id: layouts.spree.base_mailer
                  key: layouts/spree/base_mailer
                  subject:
                  body: |
                    {% assign brand = store.branding %}<mjml lang="{{ locale }}">
                      <mj-head>
                        <mj-title>{{ subject }}</mj-title>
                        {% if brand.font_url %}<mj-font name="{{ brand.font_family | split: ',' | first }}" href="{{ brand.font_url }}" />{% endif %}
                        <mj-attributes>
                          <mj-all font-family="{{ brand.font_family }}" />
                          <mj-section padding="0" />
                          <mj-column padding="0" />
                          <mj-text padding="0" color="{{ brand.text_color }}" font-size="14px" line-height="1.6" align="center" />
                          <mj-button background-color="{{ brand.button_color }}" border="{{ brand.button_border }}" border-radius="8px" color="{{ brand.button_text_color }}" font-size="15px" font-weight="500" line-height="1.6" inner-padding="12px 20px" padding="32px 0 0" />
                          <mj-table padding="0" color="{{ brand.text_color }}" font-size="14px" line-height="1.6" />
                          <mj-class name="heading" font-family="{{ brand.heading_font_family }}" font-size="40px" font-weight="700" line-height="1.2" letter-spacing="-0.8px" color="{{ brand.heading_color }}" css-class="heading" />
                          <mj-class name="greeting" padding="24px 0 0" font-size="15px" font-weight="500" color="{{ brand.heading_color }}" />
                          <mj-class name="lead" padding="12px 0 0" />
                          <mj-class name="note" padding="24px 0 0" font-size="13px" css-class="note" />
                          <mj-class name="section-heading" padding="48px 0 16px" font-family="{{ brand.heading_font_family }}" font-size="16px" font-weight="500" letter-spacing="-0.16px" align="left" />
                          <mj-class name="body" padding="16px 0 0" align="left" />
                          <mj-class name="footer" padding="12px 0 0" font-size="11px" line-height="1.5" />
                        </mj-attributes>
                        <mj-style>
                          {% if brand.font == 'inter' %}
                          @font-face { font-family: "Geist"; font-style: normal; font-weight: 500 700; src: url("https://fonts.gstatic.com/s/geist/v4/gyByhwUxId8gMEwcGFU.woff2") format("woff2"); }
                          @font-face { font-family: "Inter"; font-style: normal; font-weight: 400 450; src: url("https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuOKfMZg.ttf") format("truetype"); }
                          @font-face { font-family: "Inter"; font-style: normal; font-weight: 500; src: url("https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuI6fMZg.ttf") format("truetype"); }
                          @font-face { font-family: "Inter"; font-style: normal; font-weight: 600; src: url("https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuGKYMZg.ttf") format("truetype"); }
                          {% endif %}
                          a { color: {{ brand.link_color }}; }
                          .hero > table { max-width: 420px; margin: 0 auto; }
                          .note a { color: {{ brand.text_color }}; word-break: break-all; }
                          .footer a { color: {{ brand.text_color }}; }
                          .item { width: 100%; background-color: #F0F0F0; border-radius: 16px; margin: 0 0 8px; }
                          .item_image { padding: 8px; width: 96px; }
                          .item_thumb { display: block; width: 80px; height: auto; border-radius: 12px; }
                          .item_thumb_placeholder { width: 80px; height: 80px; background-color: #E4E4E4; border-radius: 12px; }
                          .item_info { padding: 8px 16px 8px 8px; }
                          .item_name { font-size: 15px; line-height: 1.5; font-weight: 500; color: {{ brand.heading_color }}; text-decoration: none; }
                          .item_meta { margin: 2px 0 0; font-size: 13px; line-height: 1.5; color: {{ brand.text_color }}; }
                          .item_amount { padding: 8px 16px 8px 8px; text-align: right; white-space: nowrap; }
                          .item_qty { margin: 0; font-size: 13px; line-height: 1.5; color: {{ brand.text_color }}; }
                          .item_price { margin: 2px 0 0; font-size: 15px; line-height: 1.5; font-weight: 500; color: {{ brand.heading_color }}; }
                          .summary td { padding: 6px 0; font-size: 14px; line-height: 1.6; color: {{ brand.text_color }}; }
                          .summary_value { font-size: 15px; font-weight: 500; text-align: right; white-space: nowrap; color: {{ brand.heading_color }}; }
                          .summary_sub { display: block; font-size: 13px; line-height: 1.5; }
                          .summary_total td { padding: 14px 0 0; border-top: 1px solid #E8E9E9; font-weight: 500; color: {{ brand.heading_color }}; }
                          .summary_total .summary_value { font-weight: 600; }
                          .mailer_hero h1 { margin: 0; font-family: {{ brand.heading_font_family }}; font-size: 40px; line-height: 1.2; letter-spacing: -0.8px; font-weight: 700; color: {{ brand.heading_color }}; }
                          .mailer_hero p { margin: 12px 0 0; }
                          .mailer_hero .greeting { margin-top: 24px; font-size: 15px; font-weight: 500; color: {{ brand.heading_color }}; }
                          .mailer_hero .sub { margin-top: 24px; font-size: 13px; }
                          @media only screen and (max-width: 600px) {
                            .heading div { font-size: 32px !important; letter-spacing: -0.64px !important; }
                          }
                        </mj-style>
                      </mj-head>
                      <mj-body background-color="{{ brand.background_color }}" width="640px">
                        <mj-wrapper background-color="{{ brand.card_color }}" padding="56px 24px">
                          <mj-section padding="0 0 32px">
                            <mj-column>
                              {% if store.logo_url and store.logo_width %}
                                <mj-image src="{{ store.logo_url }}" href="{{ store.url }}" alt="{{ store.name }}" width="{{ store.logo_width }}px" height="32px" padding="0" />
                              {% elsif store.logo_url %}
                                <mj-text><a href="{{ store.url }}"><img src="{{ store.logo_url }}" alt="{{ store.name }}" height="32" style="height: 32px; width: auto; border: 0;" /></a></mj-text>
                              {% else %}
                                <mj-text font-size="22px" font-weight="700" color="{{ brand.heading_color }}" text-transform="uppercase"><a href="{{ store.url }}" style="color: {{ brand.heading_color }}; text-decoration: none;">{{ store.name }}</a></mj-text>
                              {% endif %}
                            </mj-column>
                          </mj-section>
                          {{ content_for_layout }}
                        </mj-wrapper>
                        <mj-section padding="64px 24px">
                          <mj-column>
                            <mj-text font-size="13px" line-height="1.5" css-class="footer"><a href="{{ store.url }}" style="font-weight: 500; text-decoration: none;">{{ store.name }}</a></mj-text>
                            {% if store.address != blank %}<mj-text mj-class="footer">{{ store.address }}</mj-text>{% endif %}
                            {% if store.support_email != blank %}<mj-text mj-class="footer" css-class="footer"><a href="mailto:{{ store.support_email }}">{{ store.support_email }}</a></mj-text>{% endif %}
                            <mj-text mj-class="footer" padding="20px 0 0">&copy; {{ 'now' | date: '%Y' }} {{ store.name }}</mj-text>
                          </mj-column>
                        </mj-section>
                      </mj-body>
                    </mjml>
                  language: any
                  customized_languages: []
                  kind: layout
                  customized: false
                  published_at:
                  default_subject:
                  default_body: |
                    {% assign brand = store.branding %}<mjml lang="{{ locale }}">
                      <mj-head>
                        <mj-title>{{ subject }}</mj-title>
                        {% if brand.font_url %}<mj-font name="{{ brand.font_family | split: ',' | first }}" href="{{ brand.font_url }}" />{% endif %}
                        <mj-attributes>
                          <mj-all font-family="{{ brand.font_family }}" />
                          <mj-section padding="0" />
                          <mj-column padding="0" />
                          <mj-text padding="0" color="{{ brand.text_color }}" font-size="14px" line-height="1.6" align="center" />
                          <mj-button background-color="{{ brand.button_color }}" border="{{ brand.button_border }}" border-radius="8px" color="{{ brand.button_text_color }}" font-size="15px" font-weight="500" line-height="1.6" inner-padding="12px 20px" padding="32px 0 0" />
                          <mj-table padding="0" color="{{ brand.text_color }}" font-size="14px" line-height="1.6" />
                          <mj-class name="heading" font-family="{{ brand.heading_font_family }}" font-size="40px" font-weight="700" line-height="1.2" letter-spacing="-0.8px" color="{{ brand.heading_color }}" css-class="heading" />
                          <mj-class name="greeting" padding="24px 0 0" font-size="15px" font-weight="500" color="{{ brand.heading_color }}" />
                          <mj-class name="lead" padding="12px 0 0" />
                          <mj-class name="note" padding="24px 0 0" font-size="13px" css-class="note" />
                          <mj-class name="section-heading" padding="48px 0 16px" font-family="{{ brand.heading_font_family }}" font-size="16px" font-weight="500" letter-spacing="-0.16px" align="left" />
                          <mj-class name="body" padding="16px 0 0" align="left" />
                          <mj-class name="footer" padding="12px 0 0" font-size="11px" line-height="1.5" />
                        </mj-attributes>
                        <mj-style>
                          {% if brand.font == 'inter' %}
                          @font-face { font-family: "Geist"; font-style: normal; font-weight: 500 700; src: url("https://fonts.gstatic.com/s/geist/v4/gyByhwUxId8gMEwcGFU.woff2") format("woff2"); }
                          @font-face { font-family: "Inter"; font-style: normal; font-weight: 400 450; src: url("https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuOKfMZg.ttf") format("truetype"); }
                          @font-face { font-family: "Inter"; font-style: normal; font-weight: 500; src: url("https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuI6fMZg.ttf") format("truetype"); }
                          @font-face { font-family: "Inter"; font-style: normal; font-weight: 600; src: url("https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuGKYMZg.ttf") format("truetype"); }
                          {% endif %}
                          a { color: {{ brand.link_color }}; }
                          .hero > table { max-width: 420px; margin: 0 auto; }
                          .note a { color: {{ brand.text_color }}; word-break: break-all; }
                          .footer a { color: {{ brand.text_color }}; }
                          .item { width: 100%; background-color: #F0F0F0; border-radius: 16px; margin: 0 0 8px; }
                          .item_image { padding: 8px; width: 96px; }
                          .item_thumb { display: block; width: 80px; height: auto; border-radius: 12px; }
                          .item_thumb_placeholder { width: 80px; height: 80px; background-color: #E4E4E4; border-radius: 12px; }
                          .item_info { padding: 8px 16px 8px 8px; }
                          .item_name { font-size: 15px; line-height: 1.5; font-weight: 500; color: {{ brand.heading_color }}; text-decoration: none; }
                          .item_meta { margin: 2px 0 0; font-size: 13px; line-height: 1.5; color: {{ brand.text_color }}; }
                          .item_amount { padding: 8px 16px 8px 8px; text-align: right; white-space: nowrap; }
                          .item_qty { margin: 0; font-size: 13px; line-height: 1.5; color: {{ brand.text_color }}; }
                          .item_price { margin: 2px 0 0; font-size: 15px; line-height: 1.5; font-weight: 500; color: {{ brand.heading_color }}; }
                          .summary td { padding: 6px 0; font-size: 14px; line-height: 1.6; color: {{ brand.text_color }}; }
                          .summary_value { font-size: 15px; font-weight: 500; text-align: right; white-space: nowrap; color: {{ brand.heading_color }}; }
                          .summary_sub { display: block; font-size: 13px; line-height: 1.5; }
                          .summary_total td { padding: 14px 0 0; border-top: 1px solid #E8E9E9; font-weight: 500; color: {{ brand.heading_color }}; }
                          .summary_total .summary_value { font-weight: 600; }
                          .mailer_hero h1 { margin: 0; font-family: {{ brand.heading_font_family }}; font-size: 40px; line-height: 1.2; letter-spacing: -0.8px; font-weight: 700; color: {{ brand.heading_color }}; }
                          .mailer_hero p { margin: 12px 0 0; }
                          .mailer_hero .greeting { margin-top: 24px; font-size: 15px; font-weight: 500; color: {{ brand.heading_color }}; }
                          .mailer_hero .sub { margin-top: 24px; font-size: 13px; }
                          @media only screen and (max-width: 600px) {
                            .heading div { font-size: 32px !important; letter-spacing: -0.64px !important; }
                          }
                        </mj-style>
                      </mj-head>
                      <mj-body background-color="{{ brand.background_color }}" width="640px">
                        <mj-wrapper background-color="{{ brand.card_color }}" padding="56px 24px">
                          <mj-section padding="0 0 32px">
                            <mj-column>
                              {% if store.logo_url and store.logo_width %}
                                <mj-image src="{{ store.logo_url }}" href="{{ store.url }}" alt="{{ store.name }}" width="{{ store.logo_width }}px" height="32px" padding="0" />
                              {% elsif store.logo_url %}
                                <mj-text><a href="{{ store.url }}"><img src="{{ store.logo_url }}" alt="{{ store.name }}" height="32" style="height: 32px; width: auto; border: 0;" /></a></mj-text>
                              {% else %}
                                <mj-text font-size="22px" font-weight="700" color="{{ brand.heading_color }}" text-transform="uppercase"><a href="{{ store.url }}" style="color: {{ brand.heading_color }}; text-decoration: none;">{{ store.name }}</a></mj-text>
                              {% endif %}
                            </mj-column>
                          </mj-section>
                          {{ content_for_layout }}
                        </mj-wrapper>
                        <mj-section padding="64px 24px">
                          <mj-column>
                            <mj-text font-size="13px" line-height="1.5" css-class="footer"><a href="{{ store.url }}" style="font-weight: 500; text-decoration: none;">{{ store.name }}</a></mj-text>
                            {% if store.address != blank %}<mj-text mj-class="footer">{{ store.address }}</mj-text>{% endif %}
                            {% if store.support_email != blank %}<mj-text mj-class="footer" css-class="footer"><a href="mailto:{{ store.support_email }}">{{ store.support_email }}</a></mj-text>{% endif %}
                            <mj-text mj-class="footer" padding="20px 0 0">&copy; {{ 'now' | date: '%Y' }} {{ store.name }}</mj-text>
                          </mj-column>
                        </mj-section>
                      </mj-body>
                    </mjml>
                  published_language:
                  default_changed: false
                  base_subject:
                  base_body:
                  draft:
                meta: {}
  "/api/v3/admin/email_templates/{id}":
    parameters:
    - name: id
      in: path
      required: true
      description: The template key with dots, e.g. `spree.order_mailer.confirm_email`
      schema:
        type: string
    get:
      summary: Get an email template
      tags:
      - Email Templates
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the template for one language: what customers receive now,
        Spree's default, and the draft with its `lock_version`. When Spree's
        default changed since the store's version started from it,
        `default_changed` is true and `base_body` holds the default it
        started from, to compare with `default_body`.


        **Required scope:** `read_email_templates` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const template = await client.emailTemplates.get('spree.order_mailer.confirm_email', {
            language: 'de',
            expand: ['draft.updated_by'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /email_templates/{id} -d '{"language":"de","expand":["draft.updated_by"]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: language
        in: query
        required: false
        description: A language code, or `any` (the default)
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (`draft.updated_by`)
        schema:
          type: string
      responses:
        '200':
          description: email template found
          content:
            application/json:
              example:
                id: spree.order_mailer.confirm_email
                key: spree/order_mailer/confirm_email
                subject: Order {{ order.number }} confirmed
                body: "<mj-section><mj-column><mj-text>Thanks for your order, {{ order.customer_name
                  }}!</mj-text></mj-column></mj-section>\n"
                language: any
                customized_languages: []
                kind: email
                customized: false
                published_at:
                default_subject: Order {{ order.number }} confirmed
                default_body: "<mj-section><mj-column><mj-text>Thanks for your order,
                  {{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"
                published_language:
                default_changed: true
                base_subject: Reset {{ store.name }}
                base_body: "<mj-section><mj-column><mj-text>Default</mj-text></mj-column></mj-section>"
                draft:
                  id: etdr_UkLWZg9DAJ
                  subject: Reset {{ store.name }}
                  body: "<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name
                    }}!</mj-text></mj-column></mj-section>"
                  lock_version: 0
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  updated_by_id: adm_UkLWZg9DAJ
                  updated_by_type: admin_user
              schema:
                "$ref": "#/components/schemas/EmailTemplate"
        '404':
          description: not an editable template
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: record not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    delete:
      summary: Revert an email template to Spree's default
      tags:
      - Email Templates
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Goes back to Spree's default for one language and discards the draft.
        The store's published versions are kept, so one can still be restored.


        **Required scope:** `write_email_templates` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Goes back to Spree's default. Published versions stay in the history.
          const template = await client.emailTemplates.revert('spree.order_mailer.confirm_email')
      - lang: bash
        label: Spree CLI
        source: spree api delete /email_templates/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: language
        in: query
        required: false
        description: A language code, or `any` (the default)
        schema:
          type: string
      - name: lock_version
        in: query
        required: false
        description: The draft's `lock_version` as last seen; a draft saved since
          is refused with 409
        schema:
          type: integer
      responses:
        '200':
          description: email template reverted
          content:
            application/json:
              example:
                id: spree.order_mailer.confirm_email
                key: spree/order_mailer/confirm_email
                subject: Order {{ order.number }} confirmed
                body: "<mj-section><mj-column><mj-text>Thanks for your order, {{ order.customer_name
                  }}!</mj-text></mj-column></mj-section>\n"
                language: any
                customized_languages: []
                kind: email
                customized: false
                published_at:
                default_subject: Order {{ order.number }} confirmed
                default_body: "<mj-section><mj-column><mj-text>Thanks for your order,
                  {{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"
                published_language:
                default_changed: false
                base_subject:
                base_body:
                draft:
              schema:
                "$ref": "#/components/schemas/EmailTemplate"
  "/api/v3/admin/email_templates/{email_template_id}/draft":
    parameters:
    - name: email_template_id
      in: path
      required: true
      description: The template key with dots
      schema:
        type: string
    put:
      summary: Save an email template draft
      tags:
      - Email Templates
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Saves the draft, in any state; customers keep receiving the published
        version until it is published. Send the `lock_version` the draft was
        loaded with: a save made from an older copy is refused with 409,
        naming who saved last. The first save starts from what is published,
        else Spree's default.


        **Required scope:** `write_email_templates` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Pass the lock_version the draft was loaded with: a save made from an
          // older copy is refused with 409, naming who saved last.
          const template = await client.emailTemplates.draft.update('spree.order_mailer.confirm_email', {
            subject: 'Your order {{ order.number }} is confirmed',
            body: '<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>',
            lock_version: 0,
          })
      - lang: bash
        label: Spree CLI
        source: spree api put /email_templates/{email_template_id}/draft -d '{"subject":"Your
          order {{ order.number }} is confirmed","body":"<mj-section><mj-column><mj-text>Thanks,
          {{ order.customer_name }}!</mj-text></mj-column></mj-section>","lock_version":0}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: draft saved
          content:
            application/json:
              example:
                id: spree.order_mailer.confirm_email
                key: spree/order_mailer/confirm_email
                subject: Order {{ order.number }} confirmed
                body: "<mj-section><mj-column><mj-text>Thanks for your order, {{ order.customer_name
                  }}!</mj-text></mj-column></mj-section>\n"
                language: any
                customized_languages: []
                kind: email
                customized: false
                published_at:
                default_subject: Order {{ order.number }} confirmed
                default_body: "<mj-section><mj-column><mj-text>Thanks for your order,
                  {{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"
                published_language:
                default_changed: false
                base_subject:
                base_body:
                draft:
                  id: etdr_UkLWZg9DAJ
                  subject: Your order {{ order.number }} is confirmed
                  body: "<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name
                    }}!</mj-text></mj-column></mj-section>"
                  lock_version: 0
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  updated_by_id: adm_UkLWZg9DAJ
                  updated_by_type: admin_user
              schema:
                "$ref": "#/components/schemas/EmailTemplate"
        '409':
          description: saved by someone else since it was loaded
          content:
            application/json:
              example:
                error:
                  code: email_template_stale
                  message: Mirta Hamill saved this draft after you opened it. Reload
                    to see their changes before saving yours.
                  details:
                    updated_by: Mirta Hamill
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/EmailTemplateDraftParams"
        required: true
    delete:
      summary: Discard an email template draft
      tags:
      - Email Templates
      security:
      - api_key: []
        bearer_auth: []
      description: "**Required scope:** `write_email_templates` (for API-key authentication)."
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const template = await client.emailTemplates.draft.delete('spree.order_mailer.confirm_email')
      - lang: bash
        label: Spree CLI
        source: spree api delete /email_templates/{email_template_id}/draft
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: language
        in: query
        required: false
        description: A language code, or `any` (the default)
        schema:
          type: string
      - name: lock_version
        in: query
        required: false
        description: The draft's `lock_version` as last seen; a draft saved since
          is refused with 409
        schema:
          type: integer
      responses:
        '200':
          description: draft discarded
          content:
            application/json:
              example:
                id: spree.order_mailer.confirm_email
                key: spree/order_mailer/confirm_email
                subject: Order {{ order.number }} confirmed
                body: "<mj-section><mj-column><mj-text>Thanks for your order, {{ order.customer_name
                  }}!</mj-text></mj-column></mj-section>\n"
                language: any
                customized_languages: []
                kind: email
                customized: false
                published_at:
                default_subject: Order {{ order.number }} confirmed
                default_body: "<mj-section><mj-column><mj-text>Thanks for your order,
                  {{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"
                published_language:
                default_changed: false
                base_subject:
                base_body:
                draft:
              schema:
                "$ref": "#/components/schemas/EmailTemplate"
  "/api/v3/admin/email_templates/{email_template_id}/publication":
    parameters:
    - name: email_template_id
      in: path
      required: true
      description: The template key with dots
      schema:
        type: string
    post:
      summary: Publish an email template draft
      tags:
      - Email Templates
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Makes the draft what customers receive. The draft is first rendered
        with sample data; one that does not render (for the layout or a
        partial: in any email using it) is refused with 422, listing each
        problem with its email and line.


        **Required scope:** `write_email_templates` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Refused with 422 and each problem's email and line when the draft does not render.
          const template = await client.emailTemplates.publish('spree.order_mailer.confirm_email')
      - lang: bash
        label: Spree CLI
        source: spree api post /email_templates/{email_template_id}/publication -d
          '{ ... }'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '201':
          description: draft published
          content:
            application/json:
              example:
                id: spree.order_mailer.confirm_email
                key: spree/order_mailer/confirm_email
                subject: Reset {{ store.name }}
                body: "<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name
                  }}!</mj-text></mj-column></mj-section>"
                language: any
                customized_languages:
                - any
                kind: email
                customized: true
                published_at: '2026-01-15T12:00:00Z'
                default_subject: Order {{ order.number }} confirmed
                default_body: "<mj-section><mj-column><mj-text>Thanks for your order,
                  {{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"
                published_language: any
                default_changed: true
                base_subject: Reset {{ store.name }}
                base_body: "<mj-section><mj-column><mj-text>Default</mj-text></mj-column></mj-section>"
                draft:
              schema:
                "$ref": "#/components/schemas/EmailTemplate"
        '422':
          description: the draft does not render
          content:
            application/json:
              example:
                error:
                  code: email_template_invalid
                  message: 'Liquid error (line 1): undefined variable nubmer'
                  details:
                    problems:
                    - email: spree.order_mailer.confirm_email
                      locale: any
                      message: 'Liquid error (line 1): undefined variable nubmer'
                      line: 1
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/EmailTemplateVersionParams"
  "/api/v3/admin/email_templates/{email_template_id}/preview":
    parameters:
    - name: email_template_id
      in: path
      required: true
      description: The template key with dots
      schema:
        type: string
    post:
      summary: Preview an email template
      tags:
      - Email Templates
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Renders the template with sample data built from the store's latest
        matching record, or the one `record_id` names, and returns the email
        with the variables it was rendered with. An unsaved `subject` and
        `body` take the place of the current version. The layout and partials
        render inside an email, `email_key` or the first one. `branding`
        previews colors and a font before they are saved to the store.


        **Required scope:** `write_email_templates` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const preview = await client.emailTemplates.preview('spree.order_mailer.confirm_email', {
            body: '<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>',
            record_id: 'or_m3Rp9wXz',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /email_templates/{email_template_id}/preview -d '{"body":"<mj-section><mj-column><mj-text>Thanks,
          {{ order.customer_name }}!</mj-text></mj-column></mj-section>","record_id":"or_m3Rp9wXz"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: email template rendered
          content:
            application/json:
              example:
                id:
                subject: Order R123456789 confirmed
                html: "<!doctype html><html lang=\"en\" dir=\"auto\" xmlns=\"http://www.w3.org/1999/xhtml\"
                  xmlns:v=\"urn:schemas-microsoft-com:vml\" xmlns:o=\"urn:schemas-microsoft-com:office:office\"><head><title>Order
                  R123456789 confirmed</title><!--[if !mso]><!--><meta http-equiv=\"X-UA-Compatible\"
                  content=\"IE=edge\"><!--<![endif]--><meta http-equiv=\"Content-Type\"
                  content=\"text/html; charset=UTF-8\"><meta name=\"viewport\" content=\"width=device-width,
                  initial-scale=1\">\n<style type=\"text/css\">\n#outlook a { padding:
                  0; }\nbody { margin: 0; padding: 0; -webkit-text-size-adjust: 100%;
                  -ms-text-size-adjust: 100%; }\ntable, td { border-collapse: collapse;
                  mso-table-lspace: 0pt; mso-table-rspace: 0pt; }\nimg { border: 0;
                  height: auto; line-height: 100%; outline: none; text-decoration:
                  none; -ms-interpolation-mode: bicubic; }\np { display: block; margin:
                  13px 0; }\n</style>\n<!--[if mso]>\n<noscript>\n<xml>\n<o:OfficeDocumentSettings>\n
                  \ <o:AllowPNG/>\n  <o:PixelsPerInch>96</o:PixelsPerInch>\n</o:OfficeDocumentSettings>\n</xml>\n</noscript>\n<![endif]-->\n<!--[if
                  lte mso 11]>\n<style type=\"text/css\">\n.mj-outlook-group-fix {
                  width:100% !important; }\n</style>\n<![endif]-->\n<style type=\"text/css\">@media
                  only screen and (min-width:480px) { .mj-column-per-100 { width:100%
                  !important; max-width:100%; }  }</style><style media=\"screen and
                  (min-width:480px)\">.moz-text-html .mj-column-per-100 { width:100%
                  !important; max-width:100%; } </style><style type=\"text/css\">@font-face
                  { font-family: \"Geist\"; font-style: normal; font-weight: 500 700;
                  src: url(\"https://fonts.gstatic.com/s/geist/v4/gyByhwUxId8gMEwcGFU.woff2\")
                  format(\"woff2\"); }\n      @font-face { font-family: \"Inter\";
                  font-style: normal; font-weight: 400 450; src: url(\"https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuOKfMZg.ttf\")
                  format(\"truetype\"); }\n      @font-face { font-family: \"Inter\";
                  font-style: normal; font-weight: 500; src: url(\"https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuI6fMZg.ttf\")
                  format(\"truetype\"); }\n      @font-face { font-family: \"Inter\";
                  font-style: normal; font-weight: 600; src: url(\"https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuGKYMZg.ttf\")
                  format(\"truetype\"); }\n      \n      a { color: #332C2C; }\n      .hero
                  > table { max-width: 420px; margin: 0 auto; }\n      .note a { color:
                  #726A6A; word-break: break-all; }\n      .footer a { color: #726A6A;
                  }\n      .item { width: 100%; background-color: #F0F0F0; border-radius:
                  16px; margin: 0 0 8px; }\n      .item_image { padding: 8px; width:
                  96px; }\n      .item_thumb { display: block; width: 80px; height:
                  auto; border-radius: 12px; }\n      .item_thumb_placeholder { width:
                  80px; height: 80px; background-color: #E4E4E4; border-radius: 12px;
                  }\n      .item_info { padding: 8px 16px 8px 8px; }\n      .item_name
                  { font-size: 15px; line-height: 1.5; font-weight: 500; color: #332C2C;
                  text-decoration: none; }\n      .item_meta { margin: 2px 0 0; font-size:
                  13px; line-height: 1.5; color: #726A6A; }\n      .item_amount {
                  padding: 8px 16px 8px 8px; text-align: right; white-space: nowrap;
                  }\n      .item_qty { margin: 0; font-size: 13px; line-height: 1.5;
                  color: #726A6A; }\n      .item_price { margin: 2px 0 0; font-size:
                  15px; line-height: 1.5; font-weight: 500; color: #332C2C; }\n      .summary
                  td { padding: 6px 0; font-size: 14px; line-height: 1.6; color: #726A6A;
                  }\n      .summary_value { font-size: 15px; font-weight: 500; text-align:
                  right; white-space: nowrap; color: #332C2C; }\n      .summary_sub
                  { display: block; font-size: 13px; line-height: 1.5; }\n      .summary_total
                  td { padding: 14px 0 0; border-top: 1px solid #E8E9E9; font-weight:
                  500; color: #332C2C; }\n      .summary_total .summary_value { font-weight:
                  600; }\n      .mailer_hero h1 { margin: 0; font-family: Geist, Inter,
                  Helvetica, Arial, sans-serif; font-size: 40px; line-height: 1.2;
                  letter-spacing: -0.8px; font-weight: 700; color: #332C2C; }\n      .mailer_hero
                  p { margin: 12px 0 0; }\n      .mailer_hero .greeting { margin-top:
                  24px; font-size: 15px; font-weight: 500; color: #332C2C; }\n      .mailer_hero
                  .sub { margin-top: 24px; font-size: 13px; }\n      @media only screen
                  and (max-width: 600px) {\n        .heading div { font-size: 32px
                  !important; letter-spacing: -0.64px !important; }\n      }</style></head><body
                  style=\"word-spacing:normal;background-color:#FFFFFF;\"><div lang=\"en\"
                  dir=\"auto\" style=\"background-color:#FFFFFF;\"><!--[if mso | IE]><table
                  border=\"0\" cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\"
                  bgcolor=\"#F6F6F6\" align=\"center\" width=\"640\" style=\"width:640px;\"><tr><td
                  style=\"line-height:0px;font-size:0px;mso-line-height-rule:exactly;\"><![endif]--><div
                  style=\"background:#F6F6F6;background-color:#F6F6F6;margin:0px auto;max-width:640px;\"><table
                  border=\"0\" cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\"
                  align=\"center\" style=\"background:#F6F6F6;background-color:#F6F6F6;width:100%;\"><tbody><tr><td
                  style=\"direction:ltr;font-size:0px;padding:56px 24px;text-align:center;\"><!--[if
                  mso | IE]><table border=\"0\" cellpadding=\"0\" cellspacing=\"0\"
                  role=\"presentation\"><tr><td width=\"640px\"><![endif]--><!--[if
                  mso | IE]><table border=\"0\" cellpadding=\"0\" cellspacing=\"0\"
                  role=\"presentation\" align=\"center\" width=\"592\" style=\"width:592px;\"><tr><td
                  style=\"line-height:0px;font-size:0px;mso-line-height-rule:exactly;\"><![endif]--><div
                  style=\"margin:0px auto;max-width:592px;\"><table border=\"0\" cellpadding=\"0\"
                  cellspacing=\"0\" role=\"presentation\" align=\"center\" style=\"width:100%;\"><tbody><tr><td
                  style=\"direction:ltr;font-size:0px;padding:0 0 32px;text-align:center;\"><!--[if
                  mso | IE]><table border=\"0\" cellpadding=\"0\" cellspacing=\"0\"
                  role=\"presentation\"><tr><![endif]--><!--[if mso | IE]><td style=\"vertical-align:top;width:592px;\"><![endif]--><div
                  class=\"mj-outlook-group-fix mj-column-per-100\" style=\"font-size:0px;text-align:left;direction:ltr;display:inline-block;vertical-align:top;width:100%;\"><table
                  border=\"0\" cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\"
                  width=\"100%\"><tbody><tr><td style=\"vertical-align:top;padding:0;\"><table
                  border=\"0\" cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\"
                  width=\"100%\"><tbody><tr><td align=\"center\" style=\"font-size:0px;padding:0;word-break:break-word;\"><div
                  style=\"font-family:Inter, Helvetica, Arial, sans-serif;font-size:22px;font-weight:700;line-height:1.6;text-align:center;text-transform:uppercase;color:#332C2C;\"><a
                  href=\"http://www.example.com:3000\" style=\"color: #332C2C; text-decoration:
                  none;\">Spree Test Store</a></div></td></tr></tbody></table></td></tr></tbody></table></div><!--[if
                  mso | IE]></td><![endif]--><!--[if mso | IE]></tr></table><![endif]--></td></tr></tbody></table></div><!--[if
                  mso | IE]></td></tr></table><![endif]--><!--[if mso | IE]></td></tr><tr><td
                  width=\"640px\"><![endif]--><!--[if mso | IE]><table border=\"0\"
                  cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\" align=\"center\"
                  width=\"592\" style=\"width:592px;\"><tr><td style=\"line-height:0px;font-size:0px;mso-line-height-rule:exactly;\"><![endif]--><div
                  style=\"margin:0px auto;max-width:592px;\"><table border=\"0\" cellpadding=\"0\"
                  cellspacing=\"0\" role=\"presentation\" align=\"center\" style=\"width:100%;\"><tbody><tr><td
                  style=\"direction:ltr;font-size:0px;padding:0;text-align:center;\"><!--[if
                  mso | IE]><table border=\"0\" cellpadding=\"0\" cellspacing=\"0\"
                  role=\"presentation\"><tr><![endif]--><!--[if mso | IE]><td style=\"vertical-align:top;width:592px;\"><![endif]--><div
                  class=\"mj-outlook-group-fix mj-column-per-100\" style=\"font-size:0px;text-align:left;direction:ltr;display:inline-block;vertical-align:top;width:100%;\"><table
                  border=\"0\" cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\"
                  width=\"100%\"><tbody><tr><td style=\"vertical-align:top;padding:0;\"><table
                  border=\"0\" cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\"
                  width=\"100%\"><tbody><tr><td align=\"center\" style=\"font-size:0px;padding:0;word-break:break-word;\"><div
                  style=\"font-family:Inter, Helvetica, Arial, sans-serif;font-size:14px;line-height:1.6;text-align:center;color:#726A6A;\">Thanks,
                  Ann Lee!</div></td></tr></tbody></table></td></tr></tbody></table></div><!--[if
                  mso | IE]></td><![endif]--><!--[if mso | IE]></tr></table><![endif]--></td></tr></tbody></table></div><!--[if
                  mso | IE]></td></tr></table><![endif]--><!--[if mso | IE]></td></tr></table><![endif]--></td></tr></tbody></table></div><!--[if
                  mso | IE]></td></tr></table><![endif]--><!--[if mso | IE]><table
                  border=\"0\" cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\"
                  align=\"center\" width=\"640\" style=\"width:640px;\"><tr><td style=\"line-height:0px;font-size:0px;mso-line-height-rule:exactly;\"><![endif]--><div
                  style=\"margin:0px auto;max-width:640px;\"><table border=\"0\" cellpadding=\"0\"
                  cellspacing=\"0\" role=\"presentation\" align=\"center\" style=\"width:100%;\"><tbody><tr><td
                  style=\"direction:ltr;font-size:0px;padding:64px 24px;text-align:center;\"><!--[if
                  mso | IE]><table border=\"0\" cellpadding=\"0\" cellspacing=\"0\"
                  role=\"presentation\"><tr><![endif]--><!--[if mso | IE]><td style=\"vertical-align:top;width:640px;\"><![endif]--><div
                  class=\"mj-outlook-group-fix mj-column-per-100\" style=\"font-size:0px;text-align:left;direction:ltr;display:inline-block;vertical-align:top;width:100%;\"><table
                  border=\"0\" cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\"
                  width=\"100%\"><tbody><tr><td style=\"vertical-align:top;padding:0;\"><table
                  border=\"0\" cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\"
                  width=\"100%\"><tbody><tr><td align=\"center\" class=\"footer\"
                  style=\"font-size:0px;padding:0;word-break:break-word;\"><div style=\"font-family:Inter,
                  Helvetica, Arial, sans-serif;font-size:13px;line-height:1.5;text-align:center;color:#726A6A;\"><a
                  href=\"http://www.example.com:3000\" style=\"font-weight: 500; text-decoration:
                  none;\">Spree Test Store</a></div></td></tr><tr><td align=\"center\"
                  class=\"footer\" style=\"font-size:0px;padding:12px 0 0;word-break:break-word;\"><div
                  style=\"font-family:Inter, Helvetica, Arial, sans-serif;font-size:11px;line-height:1.5;text-align:center;color:#726A6A;\"><a
                  href=\"mailto:[email protected]\">[email protected]</a></div></td></tr><tr><td
                  align=\"center\" style=\"font-size:0px;padding:20px 0 0;word-break:break-word;\"><div
                  style=\"font-family:Inter, Helvetica, Arial, sans-serif;font-size:11px;line-height:1.5;text-align:center;color:#726A6A;\">&copy;
                  2026 Spree Test Store</div></td></tr></tbody></table></td></tr></tbody></table></div><!--[if
                  mso | IE]></td><![endif]--><!--[if mso | IE]></tr></table><![endif]--></td></tr></tbody></table></div><!--[if
                  mso | IE]></td></tr></table><![endif]--></div></body></html>"
                text: |
                  Spree Test Store (http://www.example.com:3000)

                  Thanks, Ann Lee!

                  Spree Test Store (http://www.example.com:3000)

                  [email protected]

                  © 2026 Spree Test Store
                email_key: spree.order_mailer.confirm_email
                variables:
                  store:
                    id: store_UkLWZg9DAJ
                    name: Spree Test Store
                    address:
                    mail_from_address: [email protected]
                    default_currency: USD
                    default_locale: en
                    url: http://www.example.com:3000
                    support_email: [email protected]
                    logo_url:
                    logo_width:
                    branding:
                      background_color: "#FFFFFF"
                      card_color: "#F6F6F6"
                      text_color: "#726A6A"
                      heading_color: "#332C2C"
                      accent_color:
                      link_color: "#332C2C"
                      button_color: "#FFFFFF"
                      button_text_color: "#1F2222"
                      button_border: '1px solid #E8E9E9'
                      font: inter
                      font_family: Inter, Helvetica, Arial, sans-serif
                      heading_font_family: Geist, Inter, Helvetica, Arial, sans-serif
                      font_url:
                  locale: en
                  user:
                    first_name: Ann
                    email: [email protected]
                  order:
                    number: R123456789
                    customer_name: Ann Lee
                  reset_url: http://www.example.com:3000/reset-password?token=preview
              schema:
                "$ref": "#/components/schemas/EmailTemplatePreview"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/EmailTemplatePreviewParams"
        required: true
  "/api/v3/admin/email_templates/{email_template_id}/test_email":
    parameters:
    - name: email_template_id
      in: path
      required: true
      description: The template key with dots
      schema:
        type: string
    post:
      summary: Send a test email
      tags:
      - Email Templates
      security:
      - bearer_auth: []
      description: |
        Sends the template, rendered as the preview renders it, to the
        signed-in admin, and never to another address: the sample data comes
        from a real customer's records. Takes the same body as the preview.
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            jwtToken: 'eyJhbGciOi...',
          })

          // Sent to the signed-in admin, so this needs a client created with `jwtToken`;
          // a secret key has no inbox and is refused.
          const { sent_to } = await client.emailTemplates.sendTest('spree.order_mailer.confirm_email', {
            body: '<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /email_templates/{email_template_id}/test_email -d
          '{"body":"<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name
          }}!</mj-text></mj-column></mj-section>"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '202':
          description: test email queued
          content:
            application/json:
              example:
                sent_to: [email protected]
              schema:
                type: object
                properties:
                  sent_to:
                    type: string
                required:
                - sent_to
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/EmailTemplatePreviewParams"
        required: true
  "/api/v3/admin/email_templates/{email_template_id}/sample_records":
    parameters:
    - name: email_template_id
      in: path
      required: true
      description: The template key with dots
      schema:
        type: string
    get:
      summary: List records to preview an email template with
      tags:
      - Email Templates
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        The store's five latest records the template can be previewed with,
        newest first, to pass as `record_id` to the preview. For the layout
        and partials, those of the email `email_key` names. Empty for an
        email that needs no record.


        **Required scope:** `write_email_templates` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // The latest orders to preview the order confirmation with; pass one's id as `record_id`.
          const { data: records } = await client.emailTemplates.sampleRecords.list(
            'spree.order_mailer.confirm_email',
          )
      - lang: bash
        label: Spree CLI
        source: spree api get /email_templates/{email_template_id}/sample_records
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: email_key
        in: query
        required: false
        description: For the layout or a partial, the email to show it in
        schema:
          type: string
      responses:
        '200':
          description: records found
          content:
            application/json:
              example:
                data:
                - id: or_UkLWZg9DAJ
                  label: R1001
                  created_at: '2026-01-15T12:00:00.000Z'
  "/api/v3/admin/email_templates/{email_template_id}/revisions":
    parameters:
    - name: email_template_id
      in: path
      required: true
      description: The template key with dots
      schema:
        type: string
    get:
      summary: List email template revisions
      tags:
      - Email Templates
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Every version of the template published in one language, newest
        first. Reverting to Spree's default keeps them.


        **Required scope:** `read_email_templates` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const revisions = await client.emailTemplates.revisions.list('spree.order_mailer.confirm_email', {
            expand: ['published_by'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /email_templates/{email_template_id}/revisions -d '{"expand":["published_by"]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: language
        in: query
        required: false
        description: A language code, or `any` (the default)
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (`published_by`)
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |

          **Sort by:** `created_at`, `id`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: EmailTemplateRevision
        sortable:
        - created_at
        - id
      responses:
        '200':
          description: revisions found
          content:
            application/json:
              example:
                data:
                - id: etrv_UkLWZg9DAJ
                  subject: Reset {{ store.name }}
                  body: "<mj-section><mj-column><mj-text>Hello</mj-text></mj-column></mj-section>"
                  created_at: '2026-01-15T12:00:00.000Z'
                  published_by_id: adm_UkLWZg9DAJ
                  published_by_type: admin_user
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
  "/api/v3/admin/email_templates/{email_template_id}/revisions/{revision_id}/restoration":
    parameters:
    - name: email_template_id
      in: path
      required: true
      description: The template key with dots
      schema:
        type: string
    - name: revision_id
      in: path
      required: true
      schema:
        type: string
    post:
      summary: Restore an email template revision
      tags:
      - Email Templates
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Copies the revision into the draft, to be published like any change.
        Send the draft's `lock_version` when one is open, as when saving it.


        **Required scope:** `write_email_templates` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Copies the revision into the draft, to publish like any change.
          const template = await client.emailTemplates.revisions.restore(
            'spree.order_mailer.confirm_email',
            'etrv_k5nR8xLq',
          )
      - lang: bash
        label: Spree CLI
        source: spree api post /email_templates/{email_template_id}/revisions/{revision_id}/restoration
          -d '{ ... }'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '201':
          description: revision copied into the draft
          content:
            application/json:
              example:
                id: spree.order_mailer.confirm_email
                key: spree/order_mailer/confirm_email
                subject: Reset {{ store.name }}
                body: "<mj-section><mj-column><mj-text>Hello</mj-text></mj-column></mj-section>"
                language: any
                customized_languages:
                - any
                kind: email
                customized: true
                published_at: '2026-01-15T12:00:00Z'
                default_subject: Order {{ order.number }} confirmed
                default_body: "<mj-section><mj-column><mj-text>Thanks for your order,
                  {{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"
                published_language: any
                default_changed: true
                base_subject: Reset {{ store.name }}
                base_body: "<mj-section><mj-column><mj-text>Default</mj-text></mj-column></mj-section>"
                draft:
                  id: etdr_UkLWZg9DAJ
                  subject: Reset {{ store.name }}
                  body: "<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name
                    }}!</mj-text></mj-column></mj-section>"
                  lock_version: 0
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  updated_by_id: adm_UkLWZg9DAJ
                  updated_by_type: admin_user
              schema:
                "$ref": "#/components/schemas/EmailTemplate"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/EmailTemplateRestoreParams"
  "/api/v3/admin/exports":
    get:
      summary: List exports
      tags:
      - Exports
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).

        **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: exports } = await client.exports.list()
      - lang: bash
        label: Spree CLI
        source: spree api get /exports
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `format` | One of `csv` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |

          </Accordion>

          **Sort by:** `created_at`, `format`, `id`, `number`, `seller_id`, `type`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Export
        sortable:
        - created_at
        - format
        - id
        - number
        - seller_id
        - type
        - updated_at
      responses:
        '200':
          description: exports found
          content:
            application/json:
              example:
                data:
                - id: exp_UkLWZg9DAJ
                  number: EF1001
                  format: csv
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  type: products
                  user_id: adm_UkLWZg9DAJ
                  done: false
                  store_id: store_UkLWZg9DAJ
                  seller_id:
                  seller_name:
                  filename:
                  byte_size:
                  download_url:
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
    post:
      summary: Create an export
      tags:
      - Exports
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Queues a CSV export. The `type` selects the dataset; `search_params` is an
        optional Ransack query (same shape used by the `q[...]` params on list endpoints)
        that filters which records are exported. Pass `record_selection: "all"` to
        clear the filter server-side and export everything in scope.

        Generation is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,
        then redirect the browser to `download_url` to fetch the file.


        **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const exp = await client.exports.create({
            type: 'products',
            search_params: { name_cont: 'shirt' },
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /exports -d '{"type":"products","search_params":{"name_cont":"shirt"}}'
      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: export queued
          content:
            application/json:
              example:
                id: exp_gbHJdmfrXB
                number: EF1002
                format: csv
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                type: products
                user_id: adm_UkLWZg9DAJ
                done: false
                store_id: store_UkLWZg9DAJ
                seller_id:
                seller_name:
                filename:
                byte_size:
                download_url:
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ExportCreateParams"
        required: true
  "/api/v3/admin/exports/{id}":
    get:
      summary: Show an export
      tags:
      - Exports
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns export status. While `done` is `false`, the SPA continues polling.

        **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const exp = await client.exports.get('exp_xxx')
      - lang: bash
        label: Spree CLI
        source: spree api get /exports/{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
        schema:
          type: string
      responses:
        '200':
          description: export found
          content:
            application/json:
              example:
                id: exp_UkLWZg9DAJ
                number: EF1001
                format: csv
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                type: products
                user_id: adm_UkLWZg9DAJ
                done: false
                store_id: store_UkLWZg9DAJ
                seller_id:
                seller_name:
                filename:
                byte_size:
                download_url:
    delete:
      summary: Delete an export
      tags:
      - Exports
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Removes the export and purges its attachment.

        **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.exports.delete('exp_xxx')
      - lang: bash
        label: Spree CLI
        source: spree api delete /exports/{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
        schema:
          type: string
      responses:
        '204':
          description: export deleted
  "/api/v3/admin/exports/{id}/download":
    get:
      summary: Download an export
      tags:
      - Exports
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Streams the exported CSV with `Content-Disposition: attachment`. Returns 422 with `code: export_not_ready` while `done` is still `false`. The endpoint is JWT/API-key protected, so SPA clients must fetch it (with `Authorization` header) and trigger the browser download via a Blob URL — a top-level navigation cannot carry the JWT.

        **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Fetch with the Bearer token, then drive the browser download:
          const res = await fetch(exp.download_url, {
            headers: { Authorization: `Bearer ${token}` },
          })
          const blob = await res.blob()
          const url = URL.createObjectURL(blob)
          const a = Object.assign(document.createElement('a'), {
            href: url,
            download: exp.filename,
          })
          a.click()
          URL.revokeObjectURL(url)
      - lang: bash
        label: Spree CLI
        source: spree api get /exports/{id}/download
      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: CSV file
          content:
            text/csv:
              schema:
                type: string
                format: binary
  "/api/v3/admin/files":
    post:
      summary: Upload a file
      tags:
      - Files
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Accepts a file and returns a `signed_id` to send to the endpoint that
        uses it — `signed_id` on product media, `avatar_signed_id` on a
        customer, `attachment_signed_id` on an import, and so on.

        Two ways to send the bytes, one response:

        - **Presigned** (JSON): send the file's metadata, then `PUT` the bytes
          to `upload.url` with exactly `upload.headers`. Use this for anything
          large — the bytes go straight to storage.
        - **Multipart**: send the bytes in a `file` part. The file is stored
          before the response, so `upload` is null. Limited to 10 MB by default.

        `signed_id` is opaque: pass it back unchanged and never parse it. It
        stops being attachable at `expires_at`, one day after the upload.

        `visibility` picks the storage: `public` (the default) for images and
        videos customers see, `private` for documents, imports and digital
        products. Public uploads accept web images, videos and CSV; private
        uploads accept any type. `checksum` is the file's MD5 digest,
        base64-encoded — the storage service verifies the bytes against it.


        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Returns where to send the bytes: send the file to `upload.url` with
          // `upload.method` and `upload.headers`, then pass `signed_id` to the
          // endpoint that uses it.
          // `client.files.upload(file)` does both steps for you.
          const { signed_id, upload } = await client.files.create({
            filename: 'products.csv',
            content_type: 'text/csv',
            byte_size: 48213,
            checksum: 'XrY7u+Ae7tCTyyK7j1rNww==',
            visibility: 'private',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /files -d '{"filename":"products.csv","content_type":"text/csv","byte_size":48213,"checksum":"XrY7u+Ae7tCTyyK7j1rNww==","visibility":"private"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '201':
          description: presigned upload target created
          content:
            application/json:
              example:
                signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwiZXhwIjoiMjAyNi0wMS0xNlQxMjowMDowMC4wMDBaIiwicHVyIjoiYmxvYl9pZCJ9fQ==--aacde269a0019661ac951ab66e97e4338f76c0e3
                filename: products.csv
                content_type: text/csv
                byte_size: 48213
                visibility: private
                expires_at: '2026-01-16T12:00:00.000Z'
                upload:
                  method: PUT
                  url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJxcmZsMnNod3YwYmR4cWF3ZWFocDZvYjhlYzh5IiwiY29udGVudF90eXBlIjoidGV4dC9jc3YiLCJjb250ZW50X2xlbmd0aCI6NDgyMTMsImNoZWNrc3VtIjoiaGdKTXJSNkRFQjJYTloxelVRVVJWZz09Iiwic2VydmljZV9uYW1lIjoidGVzdCJ9LCJleHAiOiIyMDI2LTAxLTE1VDEyOjA1OjAwLjAwMFoiLCJwdXIiOiJibG9iX3Rva2VuIn19--c3b32cb7c8370747da83a558fab123e28b943128
                  headers:
                    Content-Type: text/csv
              schema:
                "$ref": "#/components/schemas/FileUpload"
        '422':
          description: content type not allowed for a public upload
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Content type is not included in the list
                  details:
                    content_type:
                    - value: application/x-sh
                      code: inclusion
                      message: is not included in the list
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/FileUploadCreateParams"
          multipart/form-data:
            schema:
              "$ref": "#/components/schemas/FileUploadCreateParams"
        required: true
  "/api/v3/admin/orders/{order_id}/fulfillments":
    get:
      summary: List fulfillments
      tags:
      - Fulfillments
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns all shipments for an order.

        **Required scope:** `read_fulfillments` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: fulfillments } = await client.orders.fulfillments.list('or_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /orders/{order_id}/fulfillments
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., inventory_units,
          stock_location, shipping_rates). Use dot notation for nested expand (max
          4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., number,status,tracking,cost).
          id is always included.
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `number`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Fulfillment
        sortable:
        - created_at
        - id
        - number
        - updated_at
      responses:
        '200':
          description: fulfillments found
          content:
            application/json:
              example:
                data:
                - id: ful_UkLWZg9DAJ
                  number: R1001-F1
                  tracking: U10000
                  tracking_url:
                  pickup_point_data:
                  selected_delivery_rate_id: dr_gbHJdmfrXB
                  unpriced: false
                  cost: '100.00'
                  total: '100.00'
                  discount_total: '0.00'
                  additional_tax_total: '0.00'
                  included_tax_total: '0.00'
                  tax_total: '0.00'
                  status: unfulfilled
                  fulfillment_type: shipping
                  fulfilled_at:
                  delivered_at:
                  items:
                  - item_id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                  deliveries:
                  - id: dlv_UkLWZg9DAJ
                    tracking_number: U10000
                    carrier:
                    carrier_name:
                    service:
                    status: pending
                    tracking_url:
                    estimated_delivery_at:
                    delivered_at:
                    details:
                    created_at: '2026-01-15T12:00:00.000Z'
                    updated_at: '2026-01-15T12:00:00.000Z'
                    shipping_label_id:
                  external_references: {}
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  adjustment_total: '0.00'
                  pre_tax_amount: '100.00'
                  order_id: or_UkLWZg9DAJ
                  stock_location_id: sloc_UkLWZg9DAJ
                  documents: []
                  labels: []
                  provider_generates_labels: false
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
    post:
      summary: Create a fulfillment
      tags:
      - Fulfillments
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Manually creates a fulfillment on a completed order, bypassing order routing — for example to mirror a shipment handled by an external carrier or 3PL. Moves the requested line item quantities out of their current fulfillments; when `items` is omitted, every not-yet-shipped unit is moved. Exchange and claim replacements are moved only out of a named `source_fulfillment_id`, which is how a canceled replacement is sent again. Pass `status: 'shipped'` to register an already-shipped fulfillment (fires shipped webhooks and freezes cost/carrier). When `delivery_method_id` is omitted, the fulfillment inherits the delivery method and cost of the source fulfillment(s) it fully drains — keeping the order total unchanged; partially drained splits get no carrier when shipped, and pending fulfillments are otherwise (re)priced by the standard rate engine, which selects the lowest-cost available rate. Pass `cost` to set an explicit shipping cost instead (e.g. the 3PL price) — note this changes the order total and payment state, and is guaranteed to persist only with `status: 'shipped'` (pending fulfillments are re-priced by the rate engine).

        **Required scope:** `write_fulfillments` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const fulfillment = await client.orders.fulfillments.create('or_UkLWZg9DAJ', {
            stock_location_id: 'sloc_UkLWZg9DAJ',
            tracking: 'INPOST-12345',
            delivery_method_id: 'dm_UkLWZg9DAJ',
            status: 'shipped',
            items: [{ item_id: 'li_UkLWZg9DAJ', quantity: 1 }],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /orders/{order_id}/fulfillments -d '{"stock_location_id":"sloc_UkLWZg9DAJ","tracking":"INPOST-12345","delivery_method_id":"dm_UkLWZg9DAJ","status":"shipped","items":[{"item_id":"li_UkLWZg9DAJ","quantity":1}]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      responses:
        '201':
          description: fulfillment created
          content:
            application/json:
              example:
                id: ful_gbHJdmfrXB
                number: R1001-F1
                tracking: INPOST-12345
                tracking_url:
                pickup_point_data:
                selected_delivery_rate_id: dr_EfhxLZ9ck8
                unpriced: false
                cost: '100.00'
                total: '100.00'
                discount_total: '0.00'
                additional_tax_total: '0.00'
                included_tax_total: '0.00'
                tax_total: '0.00'
                status: fulfilled
                fulfillment_type: shipping
                fulfilled_at: '2026-01-15T12:00:00.000Z'
                delivered_at:
                items:
                - item_id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                deliveries:
                - id: dlv_gbHJdmfrXB
                  tracking_number: INPOST-12345
                  carrier:
                  carrier_name:
                  service:
                  status: pending
                  tracking_url:
                  estimated_delivery_at:
                  delivered_at:
                  details:
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  shipping_label_id:
                external_references: {}
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                adjustment_total: '0.00'
                pre_tax_amount: '0.00'
                order_id: or_UkLWZg9DAJ
                stock_location_id: sloc_UkLWZg9DAJ
                documents: []
                labels: []
                provider_generates_labels: false
        '422':
          description: order not completed
          content:
            application/json:
              example:
                error:
                  code: processing_error
                  message: Fulfillments can only be created manually on completed
                    orders
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/FulfillmentCreateParams"
        required: true
  "/api/v3/admin/orders/{order_id}/fulfillments/{id}":
    get:
      summary: Show a shipment
      tags:
      - Fulfillments
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns details of a specific shipment.

        **Required scope:** `read_fulfillments` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const fulfillment = await client.orders.fulfillments.get('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /orders/{order_id}/fulfillments/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Fulfillment ID
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., inventory_units,
          stock_location, shipping_rates). Use dot notation for nested expand (max
          4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., number,status,tracking,cost).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: shipment found
          content:
            application/json:
              example:
                id: ful_UkLWZg9DAJ
                number: R1001-F1
                tracking: U10000
                tracking_url:
                pickup_point_data:
                selected_delivery_rate_id: dr_gbHJdmfrXB
                unpriced: false
                cost: '100.00'
                total: '100.00'
                discount_total: '0.00'
                additional_tax_total: '0.00'
                included_tax_total: '0.00'
                tax_total: '0.00'
                status: unfulfilled
                fulfillment_type: shipping
                fulfilled_at:
                delivered_at:
                items:
                - item_id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                deliveries:
                - id: dlv_UkLWZg9DAJ
                  tracking_number: U10000
                  carrier:
                  carrier_name:
                  service:
                  status: pending
                  tracking_url:
                  estimated_delivery_at:
                  delivered_at:
                  details:
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  shipping_label_id:
                external_references: {}
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                adjustment_total: '0.00'
                pre_tax_amount: '100.00'
                order_id: or_UkLWZg9DAJ
                stock_location_id: sloc_UkLWZg9DAJ
                documents: []
                labels: []
                provider_generates_labels: false
    patch:
      summary: Update a shipment
      tags:
      - Fulfillments
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Updates a fulfillment (tracking, delivery rate).

        **Required scope:** `write_fulfillments` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const fulfillment = await client.orders.fulfillments.update('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ', {
            tracking: '1Z999AA10123456784',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/fulfillments/{id} -d '{"tracking":"1Z999AA10123456784"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Fulfillment ID
        schema:
          type: string
      responses:
        '200':
          description: shipment updated
          content:
            application/json:
              example:
                id: ful_UkLWZg9DAJ
                number: R1001-F1
                tracking: 1Z999AA10123456784
                tracking_url: https://www.ups.com/track?tracknum=1Z999AA10123456784
                pickup_point_data:
                selected_delivery_rate_id: dr_gbHJdmfrXB
                unpriced: false
                cost: '100.00'
                total: '100.00'
                discount_total: '0.00'
                additional_tax_total: '0.00'
                included_tax_total: '0.00'
                tax_total: '0.00'
                status: unfulfilled
                fulfillment_type: shipping
                fulfilled_at:
                delivered_at:
                items:
                - item_id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                deliveries:
                - id: dlv_UkLWZg9DAJ
                  tracking_number: 1Z999AA10123456784
                  carrier: ups
                  carrier_name: UPS
                  service:
                  status: pending
                  tracking_url: https://www.ups.com/track?tracknum=1Z999AA10123456784
                  estimated_delivery_at:
                  delivered_at:
                  details:
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  shipping_label_id:
                external_references: {}
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                adjustment_total: '0.00'
                pre_tax_amount: '100.00'
                order_id: or_UkLWZg9DAJ
                stock_location_id: sloc_UkLWZg9DAJ
                documents: []
                labels: []
                provider_generates_labels: false
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/FulfillmentUpdateParams"
        required: true
  "/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":
    patch:
      summary: Fulfill a fulfillment
      tags:
      - Fulfillments
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Marks a fulfillment as fulfilled.

        **Required scope:** `write_fulfillments` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const fulfillment = await client.orders.fulfillments.fulfill('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/fulfillments/{id}/fulfill -d '{
          ... }'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Fulfillment ID
        schema:
          type: string
      responses:
        '200':
          description: fulfillment fulfilled
          content:
            application/json:
              example:
                id: ful_UkLWZg9DAJ
                number: R1001-F1
                tracking: 1Z999AA10123456784
                tracking_url: https://www.ups.com/track?tracknum=1Z999AA10123456784
                pickup_point_data:
                selected_delivery_rate_id: dr_gbHJdmfrXB
                unpriced: false
                cost: '100.00'
                total: '100.00'
                discount_total: '0.00'
                additional_tax_total: '0.00'
                included_tax_total: '0.00'
                tax_total: '0.00'
                status: fulfilled
                fulfillment_type: shipping
                fulfilled_at: '2026-01-15T12:00:00.000Z'
                delivered_at:
                items:
                - item_id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                deliveries:
                - id: dlv_UkLWZg9DAJ
                  tracking_number: 1Z999AA10123456784
                  carrier: ups
                  carrier_name: UPS
                  service:
                  status: pending
                  tracking_url: https://www.ups.com/track?tracknum=1Z999AA10123456784
                  estimated_delivery_at:
                  delivered_at:
                  details:
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  shipping_label_id:
                external_references: {}
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                adjustment_total: '0.00'
                pre_tax_amount: '100.00'
                order_id: or_UkLWZg9DAJ
                stock_location_id: sloc_UkLWZg9DAJ
                documents: []
                labels: []
                provider_generates_labels: false
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/FulfillmentFulfillParams"
  "/api/v3/admin/orders/{order_id}/fulfillments/{id}/mark_delivered":
    patch:
      summary: Mark a fulfillment delivered
      tags:
      - Fulfillments
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Records that the customer received the goods. Only a fulfilled shipment can be marked delivered.

        **Required scope:** `write_fulfillments` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const fulfillment = await client.orders.fulfillments.markDelivered(
            'or_UkLWZg9DAJ',
            'ful_UkLWZg9DAJ',
            { delivered_at: '2026-08-11T09:30:00Z' },
          )
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/fulfillments/{id}/mark_delivered
          -d '{"delivered_at":"2026-08-11T09:30:00Z"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Fulfillment ID
        schema:
          type: string
      responses:
        '200':
          description: fulfillment delivered
          content:
            application/json:
              example:
                id: ful_UkLWZg9DAJ
                number: R1001-F1
                tracking: U10000
                tracking_url:
                pickup_point_data:
                selected_delivery_rate_id: dr_gbHJdmfrXB
                unpriced: false
                cost: '100.00'
                total: '100.00'
                discount_total: '0.00'
                additional_tax_total: '0.00'
                included_tax_total: '0.00'
                tax_total: '0.00'
                status: delivered
                fulfillment_type: shipping
                fulfilled_at: '2026-01-15T12:00:00.000Z'
                delivered_at: '2026-01-15T12:00:00.000Z'
                items:
                - item_id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                deliveries:
                - id: dlv_UkLWZg9DAJ
                  tracking_number: U10000
                  carrier:
                  carrier_name:
                  service:
                  status: delivered
                  tracking_url:
                  estimated_delivery_at:
                  delivered_at: '2026-01-15T12:00:00.000Z'
                  details:
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  shipping_label_id:
                external_references: {}
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                adjustment_total: '0.00'
                pre_tax_amount: '100.00'
                order_id: or_UkLWZg9DAJ
                stock_location_id: sloc_UkLWZg9DAJ
                documents: []
                labels: []
                provider_generates_labels: false
        '422':
          description: fulfillment has not shipped
          content:
            application/json:
              example:
                error:
                  code: processing_error
                  message: Only a fulfilled shipment can be marked delivered
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/FulfillmentMarkDeliveredParams"
        required: true
  "/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":
    patch:
      summary: Cancel a fulfillment
      tags:
      - Fulfillments
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Cancels a fulfillment.

        **Required scope:** `write_fulfillments` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const fulfillment = await client.orders.fulfillments.cancel('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/fulfillments/{id}/cancel -d '{
          ... }'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Fulfillment ID
        schema:
          type: string
      responses:
        '200':
          description: fulfillment canceled
          content:
            application/json:
              example:
                id: ful_UkLWZg9DAJ
                number: R1001-F1
                tracking: U10000
                tracking_url:
                pickup_point_data:
                selected_delivery_rate_id: dr_gbHJdmfrXB
                unpriced: false
                cost: '100.00'
                total: '100.00'
                discount_total: '0.00'
                additional_tax_total: '0.00'
                included_tax_total: '0.00'
                tax_total: '0.00'
                status: canceled
                fulfillment_type: shipping
                fulfilled_at:
                delivered_at:
                items:
                - item_id: li_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  quantity: 1
                deliveries:
                - id: dlv_UkLWZg9DAJ
                  tracking_number: U10000
                  carrier:
                  carrier_name:
                  service:
                  status: pending
                  tracking_url:
                  estimated_delivery_at:
                  delivered_at:
                  details:
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  shipping_label_id:
                external_references: {}
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                adjustment_total: '0.00'
                pre_tax_amount: '100.00'
                order_id: or_UkLWZg9DAJ
                stock_location_id: sloc_UkLWZg9DAJ
                documents: []
                labels: []
                provider_generates_labels: false
  "/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":
    patch:
      summary: Split a fulfillment
      tags:
      - Fulfillments
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Transfers items from this shipment to a new shipment at a different stock location.

        **Required scope:** `write_fulfillments` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Splitting moves a quantity of one variant into its own fulfillment, so the
          // response is the order's full set: the source is re-shaped, and disappears
          // when the split drains it. Pass stock_location_id to send the new
          // fulfillment out from a different origin.
          const { data: fulfillments } = await client.orders.fulfillments.split(
            'or_UkLWZg9DAJ',
            'ful_UkLWZg9DAJ',
            {
              variant_id: 'variant_86Rf07xd4z',
              quantity: 1,
            },
          )
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/fulfillments/{id}/split -d '{"variant_id":"variant_86Rf07xd4z","quantity":1}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Fulfillment ID
        schema:
          type: string
      responses:
        '200':
          description: fulfillment split
          content:
            application/json:
              example:
                data:
                - id: ful_gbHJdmfrXB
                  number: R1001-F1
                  tracking:
                  tracking_url:
                  pickup_point_data:
                  selected_delivery_rate_id: dr_EfhxLZ9ck8
                  unpriced: false
                  cost: '10.00'
                  total: '10.00'
                  discount_total: '0.00'
                  additional_tax_total: '0.00'
                  included_tax_total: '0.00'
                  tax_total: '0.00'
                  status: unfulfilled
                  fulfillment_type: shipping
                  fulfilled_at:
                  delivered_at:
                  items:
                  - item_id: li_UkLWZg9DAJ
                    variant_id: variant_UkLWZg9DAJ
                    quantity: 1
                  deliveries: []
                  external_references: {}
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  adjustment_total: '0.00'
                  pre_tax_amount: '0.00'
                  order_id: or_UkLWZg9DAJ
                  stock_location_id: sloc_gbHJdmfrXB
                  documents: []
                  labels: []
                  provider_generates_labels: false
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/FulfillmentSplitParams"
        required: true
  "/api/v3/admin/gift_cards/{gift_card_id}/custom_fields":
    get:
      summary: List gift card custom fields
      tags:
      - Gift Cards
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the gift card's custom field values.

        **Required scope:** `read_gift_cards` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: customFields } = await client.customFields('gift_card', 'gc_UkLWZg9DAJ').list()
      - lang: bash
        label: Spree CLI
        source: spree api get /gift_cards/{gift_card_id}/custom_fields
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: gift_card_id
        in: path
        required: true
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., custom_field_definition).
          Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., key,value,namespace).
          id is always included.
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: CustomField
        sortable:
        - created_at
        - id
        - updated_at
      responses:
        '200':
          description: custom fields found
          content:
            application/json:
              example:
                data:
                - id: cf_UkLWZg9DAJ
                  label: Title
                  field_type: short_text
                  key: custom.title
                  value: wool
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  storefront_visible: true
                  custom_field_definition_id: cfdef_UkLWZg9DAJ
                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/CustomField"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
  "/api/v3/admin/gift_card_batches":
    get:
      summary: List gift card batches
      tags:
      - Gift Cards
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the gift card batches issued by the current store. Each batch
        groups the cards generated together for a campaign or bulk-issuance
        — the cards themselves live under `/admin/gift_cards` and reference
        the batch via `gift_card_batch_id`.


        **Required scope:** `read_gift_cards` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: batches } = await client.giftCardBatches.list({ page: 1, limit: 25 })
      - lang: bash
        label: Spree CLI
        source: spree api get /gift_card_batches -d '{"page":1,"limit":25}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      - name: sort
        in: query
        required: false
        description: Sort by field. Prefix with `-` for descending.
        schema:
          type: string
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[prefix_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `prefix` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `prefix`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: GiftCardBatch
        sortable:
        - created_at
        - id
        - prefix
        - updated_at
      responses:
        '200':
          description: gift card batches found
          content:
            application/json:
              example:
                data:
                - id: gcb_UkLWZg9DAJ
                  codes_count: 2
                  currency: USD
                  prefix: WELCOME
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  amount: '50.00'
                  expires_at:
                  created_by_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/GiftCardBatch"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
    post:
      summary: Create a gift card batch
      tags:
      - Gift Cards
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Issues a batch of gift cards in a single call. The server generates
        `codes_count` cards inline for small batches (configurable via
        `Spree.config.gift_card_batch_web_limit`, default 500) or enqueues
        a background job for larger ones. Each card's code is the batch
        `prefix` followed by random hex.


        **Required scope:** `write_gift_cards` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const batch = await client.giftCardBatches.create({
            prefix: 'WELCOME',
            amount: '25.00',
            currency: 'USD',
            codes_count: 100,
            expires_at: '2030-12-31',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /gift_card_batches -d '{"prefix":"WELCOME","amount":"25.00","currency":"USD","codes_count":100,"expires_at":"2030-12-31"}'
      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: gift card batch created
          content:
            application/json:
              example:
                id: gcb_gbHJdmfrXB
                codes_count: 5
                currency: USD
                prefix: NEWCAMP
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                amount: '25.00'
                expires_at: '2030-12-31'
                created_by_id: adm_UkLWZg9DAJ
              schema:
                "$ref": "#/components/schemas/GiftCardBatch"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Prefix can't be blank
                  details:
                    prefix:
                    - code: blank
                      message: can't be blank
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/GiftCardBatchCreateParams"
        required: true
  "/api/v3/admin/gift_card_batches/{id}":
    parameters:
    - name: id
      in: path
      required: true
      description: Gift card batch prefixed ID
      schema:
        type: string
    get:
      summary: Get a gift card batch
      tags:
      - Gift Cards
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a single batch.

        **Required scope:** `read_gift_cards` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const batch = await client.giftCardBatches.get('gcb_K3zr8x')
      - lang: bash
        label: Spree CLI
        source: spree api get /gift_card_batches/{id}
      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: gift card batch found
          content:
            application/json:
              example:
                id: gcb_UkLWZg9DAJ
                codes_count: 2
                currency: USD
                prefix: WELCOME
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                amount: '50.00'
                expires_at:
                created_by_id:
              schema:
                "$ref": "#/components/schemas/GiftCardBatch"
        '404':
          description: gift card batch not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Gift card batch not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/admin/gift_cards":
    get:
      summary: List gift cards
      tags:
      - Gift Cards
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the gift cards issued by the current store. Filter by
        `q[code_cont]` for code search, `q[customer_id_eq]` for cards issued
        to a specific customer, or `q[status_eq]` for status filtering.


        **Required scope:** `read_gift_cards` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: giftCards } = await client.giftCards.list({
            page: 1,
            limit: 25,
            expand: ['customer', 'created_by'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /gift_cards -d '{"page":1,"limit":25,"expand":["customer","created_by"]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of code (partial, case-insensitive).
      - name: q[active]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `active`.
      - name: q[expired]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `expired`.
      - name: q[partially_redeemed]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `partially_redeemed`.
      - name: q[redeemed]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `redeemed`.
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      - name: sort
        in: query
        required: false
        description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include. id is always included.
        schema:
          type: string
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[code_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `created_by_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `currency` | One of the `CurrencyCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `customer_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `expires_at` | Date | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `gift_card_batch_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `state` | One of `active`, `partially_redeemed`, `redeemed`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `status` | One of `active`, `partially_redeemed`, `redeemed`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[batch_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `batch_` | `created_at`, `id`, `prefix`, `updated_at` |
          | `customers_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
          | `customers_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `customers_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `customers_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |
          | `customers_orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
          | `customers_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `customers_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |
          | `customers_tags_` | `created_at`, `id`, `name`, `updated_at` |
          | `orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
          | `orders_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `orders_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
          | `orders_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
          | `orders_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
          | `orders_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
          | `orders_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
          | `orders_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
          | `orders_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `orders_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `orders_shipments_` | `created_at`, `id`, `number`, `updated_at` |
          | `orders_store_` | `created_at`, `id`, `name`, `updated_at` |
          | `orders_tags_` | `created_at`, `id`, `name`, `updated_at` |
          | `users_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
          | `users_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `users_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `users_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |
          | `users_orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
          | `users_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `users_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |
          | `users_tags_` | `created_at`, `id`, `name`, `updated_at` |

          </Accordion>

          **Sort by:** `code`, `created_at`, `created_by_id`, `currency`, `customer_id`, `expires_at`, `gift_card_batch_id`, `id`, `state`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: GiftCard
        sortable:
        - code
        - created_at
        - created_by_id
        - currency
        - customer_id
        - expires_at
        - gift_card_batch_id
        - id
        - state
        - status
        - updated_at
      responses:
        '200':
          description: gift cards found
          content:
            application/json:
              example:
                data:
                - id: gc_UkLWZg9DAJ
                  code: C5BC700C4EF16A06
                  status: active
                  currency: USD
                  amount: '50.00'
                  amount_used: '0.00'
                  amount_authorized: '0.00'
                  amount_remaining: '50.00'
                  expires_at:
                  redeemed_at:
                  expired: false
                  active: true
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  customer_id:
                  created_by_id:
                - id: gc_gbHJdmfrXB
                  code: 3BECEA5A776AD146
                  status: active
                  currency: USD
                  amount: '25.00'
                  amount_used: '0.00'
                  amount_authorized: '0.00'
                  amount_remaining: '25.00'
                  expires_at:
                  redeemed_at:
                  expired: false
                  active: true
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  customer_id:
                  created_by_id:
                meta:
                  page: 1
                  limit: 25
                  count: 2
                  pages: 1
                  from: 1
                  to: 2
                  in: 2
                  previous:
                  next:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/GiftCard"
                  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"
    post:
      summary: Create a gift card
      tags:
      - Gift Cards
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Issues a gift card scoped to the current store. The code is
        auto-generated when omitted. `currency` defaults to the store's
        configured currency. Pass `customer_id` (prefixed ID) to attach the
        card to a specific customer.


        **Required scope:** `write_gift_cards` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const giftCard = await client.giftCards.create({
            amount: '25.00',
            currency: 'USD',
            expires_at: '2030-12-31',
            customer_id: 'cus_UkLWZg9DAJ',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /gift_cards -d '{"amount":"25.00","currency":"USD","expires_at":"2030-12-31","customer_id":"cus_UkLWZg9DAJ"}'
      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: gift card created
          content:
            application/json:
              example:
                id: gc_EfhxLZ9ck8
                code: A68048412201A26B
                status: active
                currency: USD
                amount: '25.00'
                amount_used: '0.00'
                amount_authorized: '0.00'
                amount_remaining: '25.00'
                expires_at: '2030-12-31'
                redeemed_at:
                expired: false
                active: true
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                customer_id:
                created_by_id: adm_UkLWZg9DAJ
              schema:
                "$ref": "#/components/schemas/GiftCard"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Amount must be greater than 0
                  details:
                    amount:
                    - value: '0.0'
                      count: 0
                      code: greater_than
                      message: must be greater than 0
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/GiftCardCreateParams"
        required: true
  "/api/v3/admin/gift_cards/{id}":
    parameters:
    - name: id
      in: path
      required: true
      description: Gift card prefixed ID
      schema:
        type: string
    get:
      summary: Get a gift card
      tags:
      - Gift Cards
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a single gift card.

        **Required scope:** `read_gift_cards` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const giftCard = await client.giftCards.get('gc_K3zr8x', {
            expand: ['customer', 'created_by', 'orders'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /gift_cards/{id} -d '{"expand":["customer","created_by","orders"]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        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: gift card found
          content:
            application/json:
              example:
                id: gc_UkLWZg9DAJ
                code: 06BEABE5C26AA7E5
                status: active
                currency: USD
                amount: '50.00'
                amount_used: '0.00'
                amount_authorized: '0.00'
                amount_remaining: '50.00'
                expires_at:
                redeemed_at:
                expired: false
                active: true
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                customer_id:
                created_by_id:
              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"
    patch:
      summary: Update a gift card
      tags:
      - Gift Cards
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Updates an active gift card's editable attributes. Redeemed or
        partially-redeemed cards cannot be edited.


        **Required scope:** `write_gift_cards` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const giftCard = await client.giftCards.update('gc_K3zr8x', {
            amount: '75.00',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /gift_cards/{id} -d '{"amount":"75.00"}'
      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: gift card updated
          content:
            application/json:
              example:
                id: gc_UkLWZg9DAJ
                code: E34E66F15D82A3CD
                status: active
                currency: USD
                amount: '75.00'
                amount_used: '0.00'
                amount_authorized: '0.00'
                amount_remaining: '75.00'
                expires_at:
                redeemed_at:
                expired: false
                active: true
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                customer_id:
                created_by_id:
              schema:
                "$ref": "#/components/schemas/GiftCard"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/GiftCardUpdateParams"
        required: true
    delete:
      summary: Delete a gift card
      tags:
      - Gift Cards
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Deletes an unused gift card. Cards that have been redeemed or
        partially redeemed cannot be deleted and return 422.


        **Required scope:** `write_gift_cards` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.giftCards.delete('gc_K3zr8x')
      - lang: bash
        label: Spree CLI
        source: spree api delete /gift_cards/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '204':
          description: gift card deleted
        '422':
          description: redeemed gift card cannot be deleted
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Gift card cannot be deleted
  "/api/v3/admin/imports":
    get:
      summary: List imports
      tags:
      - Imports
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns CSV imports queued or completed for the current store.

        **Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: imports } = await client.imports.list({
            status_eq: 'failed',
            sort: '-created_at',
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /imports -d '{"status_eq":"failed","sort":"-created_at"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of number (partial, case-insensitive).
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `status` | One of `pending`, `mapping`, `completed_mapping`, `processing`, `completed`, `failed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |

          </Accordion>

          **Sort by:** `created_at`, `id`, `number`, `seller_id`, `status`, `type`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Import
        sortable:
        - created_at
        - id
        - number
        - seller_id
        - status
        - type
        - updated_at
      responses:
        '200':
          description: imports found
          content:
            application/json:
              example:
                data:
                - id: imp_UkLWZg9DAJ
                  number: IM1001
                  rows_count: 0
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  type: products
                  status: pending
                  store_id: store_UkLWZg9DAJ
                  seller_id:
                  user_id: adm_UkLWZg9DAJ
                  processing_errors:
                  delimiter: ","
                  price_list_id:
                  seller_name:
                  original_filename: products_import.csv
                  original_byte_size: 3627
                  original_file_url: "/api/v3/admin/imports/imp_UkLWZg9DAJ/download"
                  completed_rows_count: 0
                  failed_rows_count: 0
                  schema_fields:
                  - name: slug
                    label: Slug
                    required: true
                  - name: sku
                    label: SKU
                    required: true
                  - name: name
                    label: Name
                    required: true
                  - name: price
                    label: Price
                    required: true
                  - name: status
                    label: Status
                    required: false
                  - name: description
                    label: Description
                    required: false
                  - name: meta_title
                    label: Meta Title
                    required: false
                  - name: meta_description
                    label: Meta Description
                    required: false
                  - name: meta_keywords
                    label: Meta Keywords
                    required: false
                  - name: tags
                    label: Tags
                    required: false
                  - name: compare_at_price
                    label: Compare at Price
                    required: false
                  - name: currency
                    label: Currency
                    required: false
                  - name: width
                    label: Width
                    required: false
                  - name: height
                    label: Height
                    required: false
                  - name: depth
                    label: Depth
                    required: false
                  - name: dimensions_unit
                    label: Dimensions Unit
                    required: false
                  - name: weight
                    label: Weight
                    required: false
                  - name: weight_unit
                    label: Weight Unit
                    required: false
                  - name: available_on
                    label: Available On
                    required: false
                  - name: discontinue_on
                    label: Discontinue On
                    required: false
                  - name: track_inventory
                    label: Track Inventory
                    required: false
                  - name: inventory_count
                    label: Inventory Count
                    required: false
                  - name: inventory_backorderable
                    label: Inventory Backorderable
                    required: false
                  - name: stock_location
                    label: Stock Location
                    required: false
                  - name: tax_category
                    label: Tax Category
                    required: false
                  - name: product_type
                    label: Product Type
                    required: false
                  - name: hs_code
                    label: HS Code
                    required: false
                  - name: country_of_origin
                    label: Country of Origin
                    required: false
                  - name: customs_description
                    label: Customs Description
                    required: false
                  - name: carton
                    label: Carton
                    required: false
                  - name: units_per_carton
                    label: Units per Carton
                    required: false
                  - name: carton_weight
                    label: Carton Weight
                    required: false
                  - name: cartons_per_pallet
                    label: Cartons per Pallet
                    required: false
                  - name: image1_src
                    label: Image 1 URL
                    required: false
                  - name: image2_src
                    label: Image 2 URL
                    required: false
                  - name: image3_src
                    label: Image 3 URL
                    required: false
                  - name: option1_name
                    label: Option 1 Name
                    required: false
                  - name: option1_value
                    label: Option 1 Value
                    required: false
                  - name: option2_name
                    label: Option 2 Name
                    required: false
                  - name: option2_value
                    label: Option 2 Value
                    required: false
                  - name: option3_name
                    label: Option 3 Name
                    required: false
                  - name: option3_value
                    label: Option 3 Value
                    required: false
                  - name: category1
                    label: Category 1
                    required: false
                  - name: category2
                    label: Category 2
                    required: false
                  - name: category3
                    label: Category 3
                    required: false
                  csv_headers: []
                  sample_row: {}
                  mappings: []
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
    post:
      summary: Create an import
      tags:
      - Imports
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Queues a CSV import. Upload the file first via `POST /api/v3/admin/files`
        and pass the returned `signed_id` as `attachment_signed_id`. On success the import is in the
        `mapping` state and the response carries the mapping payload: `schema_fields`
        (the canonical columns for the type), `csv_headers`, a `sample_row`, and the
        auto-assigned `mappings`.

        Adjust mappings if needed, then call `PATCH /admin/imports/{id}/complete_mapping`
        to start processing. Poll `GET /admin/imports/{id}` while `status` is
        `completed_mapping`/`processing`; terminal statuses are `completed` and `failed`.


        **Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Upload the CSV with `client.files.upload(file, { visibility: 'private' })`
          // first and pass its `signed_id`. The import then waits in `mapping`, with the
          // columns assigned automatically.
          const productImport = await client.imports.create({
            type: 'products',
            attachment_signed_id: 'eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a1b2c3',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /imports -d '{"type":"products","attachment_signed_id":"eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a1b2c3"}'
      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: import created in mapping state
          content:
            application/json:
              example:
                id: imp_gbHJdmfrXB
                number: IM1002
                rows_count: 0
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                type: products
                status: mapping
                store_id: store_UkLWZg9DAJ
                seller_id:
                user_id: adm_UkLWZg9DAJ
                processing_errors:
                delimiter: ","
                price_list_id:
                seller_name:
                original_filename: import.csv
                original_byte_size: 44
                original_file_url: "/api/v3/admin/imports/imp_gbHJdmfrXB/download"
                completed_rows_count: 0
                failed_rows_count: 0
                schema_fields:
                - name: slug
                  label: Slug
                  required: true
                - name: sku
                  label: SKU
                  required: true
                - name: name
                  label: Name
                  required: true
                - name: price
                  label: Price
                  required: true
                - name: status
                  label: Status
                  required: false
                - name: description
                  label: Description
                  required: false
                - name: meta_title
                  label: Meta Title
                  required: false
                - name: meta_description
                  label: Meta Description
                  required: false
                - name: meta_keywords
                  label: Meta Keywords
                  required: false
                - name: tags
                  label: Tags
                  required: false
                - name: compare_at_price
                  label: Compare at Price
                  required: false
                - name: currency
                  label: Currency
                  required: false
                - name: width
                  label: Width
                  required: false
                - name: height
                  label: Height
                  required: false
                - name: depth
                  label: Depth
                  required: false
                - name: dimensions_unit
                  label: Dimensions Unit
                  required: false
                - name: weight
                  label: Weight
                  required: false
                - name: weight_unit
                  label: Weight Unit
                  required: false
                - name: available_on
                  label: Available On
                  required: false
                - name: discontinue_on
                  label: Discontinue On
                  required: false
                - name: track_inventory
                  label: Track Inventory
                  required: false
                - name: inventory_count
                  label: Inventory Count
                  required: false
                - name: inventory_backorderable
                  label: Inventory Backorderable
                  required: false
                - name: stock_location
                  label: Stock Location
                  required: false
                - name: tax_category
                  label: Tax Category
                  required: false
                - name: product_type
                  label: Product Type
                  required: false
                - name: hs_code
                  label: HS Code
                  required: false
                - name: country_of_origin
                  label: Country of Origin
                  required: false
                - name: customs_description
                  label: Customs Description
                  required: false
                - name: carton
                  label: Carton
                  required: false
                - name: units_per_carton
                  label: Units per Carton
                  required: false
                - name: carton_weight
                  label: Carton Weight
                  required: false
                - name: cartons_per_pallet
                  label: Cartons per Pallet
                  required: false
                - name: image1_src
                  label: Image 1 URL
                  required: false
                - name: image2_src
                  label: Image 2 URL
                  required: false
                - name: image3_src
                  label: Image 3 URL
                  required: false
                - name: option1_name
                  label: Option 1 Name
                  required: false
                - name: option1_value
                  label: Option 1 Value
                  required: false
                - name: option2_name
                  label: Option 2 Name
                  required: false
                - name: option2_value
                  label: Option 2 Value
                  required: false
                - name: option3_name
                  label: Option 3 Name
                  required: false
                - name: option3_value
                  label: Option 3 Value
                  required: false
                - name: category1
                  label: Category 1
                  required: false
                - name: category2
                  label: Category 2
                  required: false
                - name: category3
                  label: Category 3
                  required: false
                csv_headers:
                - slug
                - sku
                - name
                - price
                sample_row:
                  slug: widget
                  sku: W-1
                  name: Widget
                  price: '10.00'
                mappings:
                - id: immap_UkLWZg9DAJ
                  schema_field: slug
                  file_column: slug
                  required: true
                - id: immap_gbHJdmfrXB
                  schema_field: sku
                  file_column: sku
                  required: true
                - id: immap_EfhxLZ9ck8
                  schema_field: name
                  file_column: name
                  required: true
                - id: immap_VqXmZF31wY
                  schema_field: price
                  file_column: price
                  required: true
                - id: immap_uw2YK1rnl0
                  schema_field: status
                  file_column:
                  required: false
                - id: immap_OIJLhNcSbf
                  schema_field: description
                  file_column:
                  required: false
                - id: immap_AXs1igzRC6
                  schema_field: meta_title
                  file_column:
                  required: false
                - id: immap_p6klVeMgbn
                  schema_field: meta_description
                  file_column:
                  required: false
                - id: immap_nJqfPa3Cpe
                  schema_field: meta_keywords
                  file_column:
                  required: false
                - id: immap_98FqgRua4h
                  schema_field: tags
                  file_column:
                  required: false
                - id: immap_xhoCpeNMWu
                  schema_field: compare_at_price
                  file_column:
                  required: false
                - id: immap_vEmzDoNU0H
                  schema_field: currency
                  file_column:
                  required: false
                - id: immap_2KY5XM6frI
                  schema_field: width
                  file_column:
                  required: false
                - id: immap_HOVtlDrOmL
                  schema_field: height
                  file_column:
                  required: false
                - id: immap_ed6l8wVqSM
                  schema_field: depth
                  file_column:
                  required: false
                - id: immap_s18jaGonyx
                  schema_field: dimensions_unit
                  file_column:
                  required: false
                - id: immap_GZUcnUYI5A
                  schema_field: weight
                  file_column:
                  required: false
                - id: immap_ROeNhrwyV9
                  schema_field: weight_unit
                  file_column:
                  required: false
                - id: immap_L3pHOn63Vw
                  schema_field: available_on
                  file_column:
                  required: false
                - id: immap_PQNMcnNFWw
                  schema_field: discontinue_on
                  file_column:
                  required: false
                - id: immap_C9SrJgpzQ4
                  schema_field: track_inventory
                  file_column:
                  required: false
                - id: immap_YHETxCGlb0
                  schema_field: inventory_count
                  file_column:
                  required: false
                - id: immap_5OQZnCRf8J
                  schema_field: inventory_backorderable
                  file_column:
                  required: false
                - id: immap_F0GX8NaP3Y
                  schema_field: stock_location
                  file_column:
                  required: false
                - id: immap_kOKT9MVfb0
                  schema_field: tax_category
                  file_column:
                  required: false
                - id: immap_3uWpPTcf5W
                  schema_field: product_type
                  file_column:
                  required: false
                - id: immap_D6Psx31WaT
                  schema_field: hs_code
                  file_column:
                  required: false
                - id: immap_msx3nOJap6
                  schema_field: country_of_origin
                  file_column:
                  required: false
                - id: immap_5CQZnCRf8J
                  schema_field: customs_description
                  file_column:
                  required: false
                - id: immap_M2nyloHRUQ
                  schema_field: carton
                  file_column:
                  required: false
                - id: immap_prklVeMgbn
                  schema_field: units_per_carton
                  file_column:
                  required: false
                - id: immap_so8jaGonyx
                  schema_field: carton_weight
                  file_column:
                  required: false
                - id: immap_rsClYtECFI
                  schema_field: cartons_per_pallet
                  file_column:
                  required: false
                - id: immap_8DR0I7fEbw
                  schema_field: image1_src
                  file_column:
                  required: false
                - id: immap_aAtNvLSUAr
                  schema_field: image2_src
                  file_column:
                  required: false
                - id: immap_QiA48cIW7A
                  schema_field: image3_src
                  file_column:
                  required: false
                - id: immap_QDA48cIW7A
                  schema_field: option1_name
                  file_column:
                  required: false
                - id: immap_8cR0I7fEbw
                  schema_field: option1_value
                  file_column:
                  required: false
                - id: immap_oqlrKdXjaP
                  schema_field: option2_name
                  file_column:
                  required: false
                - id: immap_48Olu6p4zZ
                  schema_field: option2_value
                  file_column:
                  required: false
                - id: immap_qp31JYFduR
                  schema_field: option3_name
                  file_column:
                  required: false
                - id: immap_JgaEBgznCp
                  schema_field: option3_value
                  file_column:
                  required: false
                - id: immap_tXyJwvFCuK
                  schema_field: category1
                  file_column:
                  required: false
                - id: immap_NJzXvxTk8u
                  schema_field: category2
                  file_column:
                  required: false
                - id: immap_XLbb5HTmVa
                  schema_field: category3
                  file_column:
                  required: false
        '422':
          description: unknown import type
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Type can't be blank
                  details:
                    type:
                    - code: blank
                      message: can't be blank
                      specific: false
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ImportCreateParams"
        required: true
  "/api/v3/admin/imports/template":
    get:
      summary: Download an import template
      tags:
      - Imports
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a CSV header row for the given import type, including the custom field columns available for the model.

        **Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // The template is a CSV, so fetch it directly with the API key:
          const response = await fetch('https://your-store.com/api/v3/admin/imports/template?type=products', {
            headers: { 'X-Spree-API-Key': 'sk_xxx' },
          })
          if (!response.ok) throw new Error(`Download failed with status ${response.status}`)
          const csvHeader = await response.text()
      - lang: bash
        label: Spree CLI
        source: spree api get /imports/template
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: type
        in: query
        required: true
        description: Registered import type, e.g. products.
        schema:
          type: string
      responses:
        '200':
          description: CSV template
          content:
            text/csv:
              schema:
                type: string
                format: binary
  "/api/v3/admin/imports/example":
    get:
      summary: Download an example import file
      tags:
      - Imports
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Redirects to a populated example CSV for the given import type — the same sample data `rake spree:load_sample_data` uses, pinned to the installed Spree version. Returns 404 for a type that ships no example file.

        **Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Redirects to a populated example CSV; fetch follows the redirect.
          const response = await fetch('https://your-store.com/api/v3/admin/imports/example?type=products', {
            headers: { 'X-Spree-API-Key': 'sk_xxx' },
          })
          if (!response.ok) throw new Error(`Download failed with status ${response.status}`)
          const exampleCsv = await response.text()
      - lang: bash
        label: Spree CLI
        source: spree api get /imports/example
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: type
        in: query
        required: true
        description: Registered import type, e.g. products.
        schema:
          type: string
      responses:
        '302':
          description: Redirect to the example CSV
  "/api/v3/admin/imports/{id}":
    get:
      summary: Show an import
      tags:
      - Imports
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns import status and row counters. The admin dashboard polls this endpoint while `status` is `completed_mapping` or `processing`; `rows_count`, `completed_rows_count` and `failed_rows_count` drive the progress bar. The mapping payload (`csv_headers`, `sample_row`) is only present while `status` is `mapping`.

        **Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const productImport = await client.imports.get('imp_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /imports/{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
        schema:
          type: string
      responses:
        '200':
          description: import found
          content:
            application/json:
              example:
                id: imp_UkLWZg9DAJ
                number: IM1001
                rows_count: 0
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                type: products
                status: pending
                store_id: store_UkLWZg9DAJ
                seller_id:
                user_id: adm_UkLWZg9DAJ
                processing_errors:
                delimiter: ","
                price_list_id:
                seller_name:
                original_filename: products_import.csv
                original_byte_size: 3627
                original_file_url: "/api/v3/admin/imports/imp_UkLWZg9DAJ/download"
                completed_rows_count: 0
                failed_rows_count: 0
                schema_fields:
                - name: slug
                  label: Slug
                  required: true
                - name: sku
                  label: SKU
                  required: true
                - name: name
                  label: Name
                  required: true
                - name: price
                  label: Price
                  required: true
                - name: status
                  label: Status
                  required: false
                - name: description
                  label: Description
                  required: false
                - name: meta_title
                  label: Meta Title
                  required: false
                - name: meta_description
                  label: Meta Description
                  required: false
                - name: meta_keywords
                  label: Meta Keywords
                  required: false
                - name: tags
                  label: Tags
                  required: false
                - name: compare_at_price
                  label: Compare at Price
                  required: false
                - name: currency
                  label: Currency
                  required: false
                - name: width
                  label: Width
                  required: false
                - name: height
                  label: Height
                  required: false
                - name: depth
                  label: Depth
                  required: false
                - name: dimensions_unit
                  label: Dimensions Unit
                  required: false
                - name: weight
                  label: Weight
                  required: false
                - name: weight_unit
                  label: Weight Unit
                  required: false
                - name: available_on
                  label: Available On
                  required: false
                - name: discontinue_on
                  label: Discontinue On
                  required: false
                - name: track_inventory
                  label: Track Inventory
                  required: false
                - name: inventory_count
                  label: Inventory Count
                  required: false
                - name: inventory_backorderable
                  label: Inventory Backorderable
                  required: false
                - name: stock_location
                  label: Stock Location
                  required: false
                - name: tax_category
                  label: Tax Category
                  required: false
                - name: product_type
                  label: Product Type
                  required: false
                - name: hs_code
                  label: HS Code
                  required: false
                - name: country_of_origin
                  label: Country of Origin
                  required: false
                - name: customs_description
                  label: Customs Description
                  required: false
                - name: carton
                  label: Carton
                  required: false
                - name: units_per_carton
                  label: Units per Carton
                  required: false
                - name: carton_weight
                  label: Carton Weight
                  required: false
                - name: cartons_per_pallet
                  label: Cartons per Pallet
                  required: false
                - name: image1_src
                  label: Image 1 URL
                  required: false
                - name: image2_src
                  label: Image 2 URL
                  required: false
                - name: image3_src
                  label: Image 3 URL
                  required: false
                - name: option1_name
                  label: Option 1 Name
                  required: false
                - name: option1_value
                  label: Option 1 Value
                  required: false
                - name: option2_name
                  label: Option 2 Name
                  required: false
                - name: option2_value
                  label: Option 2 Value
                  required: false
                - name: option3_name
                  label: Option 3 Name
                  required: false
                - name: option3_value
                  label: Option 3 Value
                  required: false
                - name: category1
                  label: Category 1
                  required: false
                - name: category2
                  label: Category 2
                  required: false
                - name: category3
                  label: Category 3
                  required: false
                csv_headers: []
                sample_row: {}
                mappings: []
    delete:
      summary: Delete an import
      tags:
      - Imports
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.

        **Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.imports.delete('imp_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /imports/{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
        schema:
          type: string
      responses:
        '204':
          description: import deleted
  "/api/v3/admin/imports/{id}/download":
    get:
      summary: Download the originally uploaded file
      tags:
      - Imports
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Streams the CSV exactly as it was uploaded — the audit trail for what was imported. JWT/API-key protected; SPA clients fetch it with the Authorization header and trigger the browser download via a Blob URL.

        **Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const productImport = await client.imports.get('imp_UkLWZg9DAJ')

          if (productImport.original_file_url) {
            // The uploaded file is served through the API, so fetch it with the API key:
            const response = await fetch(`https://your-store.com${productImport.original_file_url}`, {
              headers: { 'X-Spree-API-Key': 'sk_xxx' },
            })
            if (!response.ok) throw new Error(`Download failed with status ${response.status}`)
            const csv = await response.text()
            console.log(csv)
          }
      - lang: bash
        label: Spree CLI
        source: spree api get /imports/{id}/download
      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: CSV file
          content:
            text/csv:
              schema:
                type: string
                format: binary
  "/api/v3/admin/imports/{id}/complete_mapping":
    patch:
      summary: Complete mapping and start processing
      tags:
      - Imports
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Applies the submitted column mappings, then starts row processing. Omit `mappings`
        to accept the auto-assigned ones from the create response. Returns 422 when a
        required schema field is left unmapped (`details.missing_required_fields`) or a
        file column is assigned twice.


        **Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Omit `mappings` to accept the columns assigned on create.
          const productImport = await client.imports.completeMapping('imp_UkLWZg9DAJ', {
            mappings: [
              { schema_field: 'slug', file_column: 'handle' },
              { schema_field: 'price', file_column: 'price_usd' },
            ],
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /imports/{id}/complete_mapping -d '{"mappings":[{"schema_field":"slug","file_column":"handle"},{"schema_field":"price","file_column":"price_usd"}]}'
      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: mapping completed, processing queued
          content:
            application/json:
              example:
                id: imp_gbHJdmfrXB
                number: IM1002
                rows_count: 0
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                type: products
                status: completed_mapping
                store_id: store_UkLWZg9DAJ
                seller_id:
                user_id: adm_UkLWZg9DAJ
                processing_errors:
                delimiter: ","
                price_list_id:
                seller_name:
                original_filename: products_import.csv
                original_byte_size: 3627
                original_file_url: "/api/v3/admin/imports/imp_gbHJdmfrXB/download"
                completed_rows_count: 0
                failed_rows_count: 0
                schema_fields:
                - name: slug
                  label: Slug
                  required: true
                - name: sku
                  label: SKU
                  required: true
                - name: name
                  label: Name
                  required: true
                - name: price
                  label: Price
                  required: true
                - name: status
                  label: Status
                  required: false
                - name: description
                  label: Description
                  required: false
                - name: meta_title
                  label: Meta Title
                  required: false
                - name: meta_description
                  label: Meta Description
                  required: false
                - name: meta_keywords
                  label: Meta Keywords
                  required: false
                - name: tags
                  label: Tags
                  required: false
                - name: compare_at_price
                  label: Compare at Price
                  required: false
                - name: currency
                  label: Currency
                  required: false
                - name: width
                  label: Width
                  required: false
                - name: height
                  label: Height
                  required: false
                - name: depth
                  label: Depth
                  required: false
                - name: dimensions_unit
                  label: Dimensions Unit
                  required: false
                - name: weight
                  label: Weight
                  required: false
                - name: weight_unit
                  label: Weight Unit
                  required: false
                - name: available_on
                  label: Available On
                  required: false
                - name: discontinue_on
                  label: Discontinue On
                  required: false
                - name: track_inventory
                  label: Track Inventory
                  required: false
                - name: inventory_count
                  label: Inventory Count
                  required: false
                - name: inventory_backorderable
                  label: Inventory Backorderable
                  required: false
                - name: stock_location
                  label: Stock Location
                  required: false
                - name: tax_category
                  label: Tax Category
                  required: false
                - name: product_type
                  label: Product Type
                  required: false
                - name: hs_code
                  label: HS Code
                  required: false
                - name: country_of_origin
                  label: Country of Origin
                  required: false
                - name: customs_description
                  label: Customs Description
                  required: false
                - name: carton
                  label: Carton
                  required: false
                - name: units_per_carton
                  label: Units per Carton
                  required: false
                - name: carton_weight
                  label: Carton Weight
                  required: false
                - name: cartons_per_pallet
                  label: Cartons per Pallet
                  required: false
                - name: image1_src
                  label: Image 1 URL
                  required: false
                - name: image2_src
                  label: Image 2 URL
                  required: false
                - name: image3_src
                  label: Image 3 URL
                  required: false
                - name: option1_name
                  label: Option 1 Name
                  required: false
                - name: option1_value
                  label: Option 1 Value
                  required: false
                - name: option2_name
                  label: Option 2 Name
                  required: false
                - name: option2_value
                  label: Option 2 Value
                  required: false
                - name: option3_name
                  label: Option 3 Name
                  required: false
                - name: option3_value
                  label: Option 3 Value
                  required: false
                - name: category1
                  label: Category 1
                  required: false
                - name: category2
                  label: Category 2
                  required: false
                - name: category3
                  label: Category 3
                  required: false
                csv_headers: []
                sample_row: {}
                mappings:
                - id: immap_UkLWZg9DAJ
                  schema_field: slug
                  file_column: slug
                  required: true
                - id: immap_gbHJdmfrXB
                  schema_field: sku
                  file_column: sku
                  required: true
                - id: immap_EfhxLZ9ck8
                  schema_field: name
                  file_column: name
                  required: true
                - id: immap_VqXmZF31wY
                  schema_field: price
                  file_column: price
                  required: true
                - id: immap_uw2YK1rnl0
                  schema_field: status
                  file_column: status
                  required: false
                - id: immap_OIJLhNcSbf
                  schema_field: description
                  file_column: description
                  required: false
                - id: immap_AXs1igzRC6
                  schema_field: meta_title
                  file_column: meta_title
                  required: false
                - id: immap_p6klVeMgbn
                  schema_field: meta_description
                  file_column: meta_description
                  required: false
                - id: immap_nJqfPa3Cpe
                  schema_field: meta_keywords
                  file_column: meta_keywords
                  required: false
                - id: immap_98FqgRua4h
                  schema_field: tags
                  file_column: tags
                  required: false
                - id: immap_xhoCpeNMWu
                  schema_field: compare_at_price
                  file_column: compare_at_price
                  required: false
                - id: immap_vEmzDoNU0H
                  schema_field: currency
                  file_column: currency
                  required: false
                - id: immap_2KY5XM6frI
                  schema_field: width
                  file_column: width
                  required: false
                - id: immap_HOVtlDrOmL
                  schema_field: height
                  file_column: height
                  required: false
                - id: immap_ed6l8wVqSM
                  schema_field: depth
                  file_column: depth
                  required: false
                - id: immap_s18jaGonyx
                  schema_field: dimensions_unit
                  file_column: dimensions_unit
                  required: false
                - id: immap_GZUcnUYI5A
                  schema_field: weight
                  file_column: weight
                  required: false
                - id: immap_ROeNhrwyV9
                  schema_field: weight_unit
                  file_column: weight_unit
                  required: false
                - id: immap_L3pHOn63Vw
                  schema_field: available_on
                  file_column: available_on
                  required: false
                - id: immap_PQNMcnNFWw
                  schema_field: discontinue_on
                  file_column: discontinue_on
                  required: false
                - id: immap_C9SrJgpzQ4
                  schema_field: track_inventory
                  file_column: track_inventory
                  required: false
                - id: immap_YHETxCGlb0
                  schema_field: inventory_count
                  file_column: inventory_count
                  required: false
                - id: immap_5OQZnCRf8J
                  schema_field: inventory_backorderable
                  file_column: inventory_backorderable
                  required: false
                - id: immap_F0GX8NaP3Y
                  schema_field: stock_location
                  file_column:
                  required: false
                - id: immap_kOKT9MVfb0
                  schema_field: tax_category
                  file_column: tax_category
                  required: false
                - id: immap_3uWpPTcf5W
                  schema_field: product_type
                  file_column:
                  required: false
                - id: immap_D6Psx31WaT
                  schema_field: hs_code
                  file_column:
                  required: false
                - id: immap_msx3nOJap6
                  schema_field: country_of_origin
                  file_column:
                  required: false
                - id: immap_5CQZnCRf8J
                  schema_field: customs_description
                  file_column:
                  required: false
                - id: immap_M2nyloHRUQ
                  schema_field: carton
                  file_column:
                  required: false
                - id: immap_prklVeMgbn
                  schema_field: units_per_carton
                  file_column:
                  required: false
                - id: immap_so8jaGonyx
                  schema_field: carton_weight
                  file_column:
                  required: false
                - id: immap_rsClYtECFI
                  schema_field: cartons_per_pallet
                  file_column:
                  required: false
                - id: immap_8DR0I7fEbw
                  schema_field: image1_src
                  file_column: image1_src
                  required: false
                - id: immap_aAtNvLSUAr
                  schema_field: image2_src
                  file_column: image2_src
                  required: false
                - id: immap_QiA48cIW7A
                  schema_field: image3_src
                  file_column: image3_src
                  required: false
                - id: immap_QDA48cIW7A
                  schema_field: option1_name
                  file_column: option1_name
                  required: false
                - id: immap_8cR0I7fEbw
                  schema_field: option1_value
                  file_column: option1_value
                  required: false
                - id: immap_oqlrKdXjaP
                  schema_field: option2_name
                  file_column: option2_name
                  required: false
                - id: immap_48Olu6p4zZ
                  schema_field: option2_value
                  file_column: option2_value
                  required: false
                - id: immap_qp31JYFduR
                  schema_field: option3_name
                  file_column: option3_name
                  required: false
                - id: immap_JgaEBgznCp
                  schema_field: option3_value
                  file_column: option3_value
                  required: false
                - id: immap_tXyJwvFCuK
                  schema_field: category1
                  file_column: category1
                  required: false
                - id: immap_NJzXvxTk8u
                  schema_field: category2
                  file_column: category2
                  required: false
                - id: immap_XLbb5HTmVa
                  schema_field: category3
                  file_column: category3
                  required: false
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ImportCompleteMappingParams"
  "/api/v3/admin/imports/{id}/retry_failed_rows":
    patch:
      summary: Retry failed rows
      tags:
      - Imports
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Re-processes the rows that failed. The import re-enters `processing`; poll `GET /admin/imports/{id}` until it completes again. Returns 422 when the import is not `completed` or has no failed rows.

        **Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const productImport = await client.imports.retryFailedRows('imp_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api patch /imports/{id}/retry_failed_rows -d '{ ... }'
      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: retry queued
          content:
            application/json:
              example:
                id: imp_gbHJdmfrXB
                number: IM1002
                rows_count: 1
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                type: products
                status: processing
                store_id: store_UkLWZg9DAJ
                seller_id:
                user_id: adm_UkLWZg9DAJ
                processing_errors:
                delimiter: ","
                price_list_id:
                seller_name:
                original_filename: products_import.csv
                original_byte_size: 3627
                original_file_url: "/api/v3/admin/imports/imp_gbHJdmfrXB/download"
                completed_rows_count: 0
                failed_rows_count: 1
                schema_fields:
                - name: slug
                  label: Slug
                  required: true
                - name: sku
                  label: SKU
                  required: true
                - name: name
                  label: Name
                  required: true
                - name: price
                  label: Price
                  required: true
                - name: status
                  label: Status
                  required: false
                - name: description
                  label: Description
                  required: false
                - name: meta_title
                  label: Meta Title
                  required: false
                - name: meta_description
                  label: Meta Description
                  required: false
                - name: meta_keywords
                  label: Meta Keywords
                  required: false
                - name: tags
                  label: Tags
                  required: false
                - name: compare_at_price
                  label: Compare at Price
                  required: false
                - name: currency
                  label: Currency
                  required: false
                - name: width
                  label: Width
                  required: false
                - name: height
                  label: Height
                  required: false
                - name: depth
                  label: Depth
                  required: false
                - name: dimensions_unit
                  label: Dimensions Unit
                  required: false
                - name: weight
                  label: Weight
                  required: false
                - name: weight_unit
                  label: Weight Unit
                  required: false
                - name: available_on
                  label: Available On
                  required: false
                - name: discontinue_on
                  label: Discontinue On
                  required: false
                - name: track_inventory
                  label: Track Inventory
                  required: false
                - name: inventory_count
                  label: Inventory Count
                  required: false
                - name: inventory_backorderable
                  label: Inventory Backorderable
                  required: false
                - name: stock_location
                  label: Stock Location
                  required: false
                - name: tax_category
                  label: Tax Category
                  required: false
                - name: product_type
                  label: Product Type
                  required: false
                - name: hs_code
                  label: HS Code
                  required: false
                - name: country_of_origin
                  label: Country of Origin
                  required: false
                - name: customs_description
                  label: Customs Description
                  required: false
                - name: carton
                  label: Carton
                  required: false
                - name: units_per_carton
                  label: Units per Carton
                  required: false
                - name: carton_weight
                  label: Carton Weight
                  required: false
                - name: cartons_per_pallet
                  label: Cartons per Pallet
                  required: false
                - name: image1_src
                  label: Image 1 URL
                  required: false
                - name: image2_src
                  label: Image 2 URL
                  required: false
                - name: image3_src
                  label: Image 3 URL
                  required: false
                - name: option1_name
                  label: Option 1 Name
                  required: false
                - name: option1_value
                  label: Option 1 Value
                  required: false
                - name: option2_name
                  label: Option 2 Name
                  required: false
                - name: option2_value
                  label: Option 2 Value
                  required: false
                - name: option3_name
                  label: Option 3 Name
                  required: false
                - name: option3_value
                  label: Option 3 Value
                  required: false
                - name: category1
                  label: Category 1
                  required: false
                - name: category2
                  label: Category 2
                  required: false
                - name: category3
                  label: Category 3
                  required: false
                csv_headers: []
                sample_row: {}
                mappings: []
  "/api/v3/admin/imports/{import_id}/rows":
    get:
      summary: List import rows
      tags:
      - Imports
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Paginated rows of an import — the failure report. Filter with `q[status_eq]=failed` to list only rows that could not be imported; each row carries the raw CSV `data` and its `validation_errors`.

        **Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: failedRows } = await client.imports.rows.list('imp_UkLWZg9DAJ', {
            status_eq: 'failed',
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /imports/{import_id}/rows -d '{"status_eq":"failed"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: import_id
        in: path
        required: true
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `row_number` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `status` | One of `pending`, `processing`, `completed`, `failed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `row_number`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: ImportRow
        sortable:
        - created_at
        - id
        - row_number
        - status
        - updated_at
      responses:
        '200':
          description: rows found
          content:
            application/json:
              example:
                data:
                - id: imrow_gbHJdmfrXB
                  row_number: 2
                  status: failed
                  validation_errors: boom
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  import_id: imp_UkLWZg9DAJ
                  item_type:
                  item_id:
                  data:
                    slug: test-product
                    name: Test Product
                    price: '10.00'
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
  "/api/v3/admin/maintenance_task_runs":
    get:
      summary: List maintenance task runs
      tags:
      - Maintenance Tasks
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        The record of every maintenance task run: who started it, with which
        arguments, how far it got and how it ended.

        Runs are installation-wide rather than per store — an upgrade step
        converts every store's data — so this list is not filtered by the
        store the request is made against.


        **Required scope:** `read_maintenance_tasks` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: runs } = await client.maintenanceTaskRuns.list({ status_eq: 'succeeded' })
      - lang: bash
        label: Spree CLI
        source: spree api get /maintenance_task_runs -d '{"status_eq":"succeeded"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q[task_name_cont]
        in: query
        required: false
        description: Filter by task name (contains), e.g. `capture`
        schema:
          type: string
      - name: q[status_eq]
        in: query
        required: false
        description: Filter by status (enqueued, running, succeeded, errored, cancelled,
          …)
        schema:
          type: string
      - name: sort
        in: query
        required: false
        description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
        schema:
          type: string
      responses:
        '200':
          description: maintenance task runs found
          content:
            application/json:
              example:
                data:
                - id: mtr_UkLWZg9DAJ
                  status: succeeded
                  dry_run: false
                  initiated_via: dashboard
                  tick_count: 0
                  tick_total:
                  error_class:
                  error_message:
                  started_at:
                  ended_at:
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  task_name: capture_methods
                  duration: 0.0
                  tallies: {}
                  arguments: {}
                  error_backtrace:
                  active: false
                  admin_user_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/MaintenanceTaskRun"
                  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"
    post:
      summary: Start a maintenance task
      tags:
      - Maintenance Tasks
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Starts a run of a registered maintenance task and returns it. The run
        is enqueued, so poll it while `active` is true.

        `arguments` are validated by the task's own Active Model validations,
        so a bad value is rejected here rather than failing on the first
        record. `dry_run` is honored only by tasks whose `supports_dry_run` is
        true — recording a run as a preview that would in fact have written
        would misrepresent what happened.

        Only one run of a task can be in flight at a time: two would race over
        the same records and their cursors would leapfrog.


        **Required scope:** `write_maintenance_tasks` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const run = await client.maintenanceTaskRuns.create({
            task_name: 'capture_methods',
            dry_run: true,
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /maintenance_task_runs -d '{"task_name":"capture_methods","dry_run":true}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '201':
          description: maintenance task started
          content:
            application/json:
              example:
                id: mtr_UkLWZg9DAJ
                status: enqueued
                dry_run: true
                initiated_via: dashboard
                tick_count: 0
                tick_total:
                error_class:
                error_message:
                started_at:
                ended_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                task_name: capture_methods
                duration: 0.0
                tallies: {}
                arguments: {}
                error_backtrace:
                active: true
                admin_user_id: adm_UkLWZg9DAJ
              schema:
                "$ref": "#/components/schemas/MaintenanceTaskRun"
        '422':
          description: task is not registered
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Task name nope is not a registered maintenance task
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MaintenanceTaskRunCreateParams"
        required: true
  "/api/v3/admin/maintenance_task_runs/{id}":
    parameters:
    - name: id
      in: path
      description: Maintenance task run ID
      required: true
      schema:
        type: string
    get:
      summary: Retrieve a maintenance task run
      tags:
      - Maintenance Tasks
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        A single run, with the progress a dashboard polls while it works.

        `progress` is `0..1` when the task could count its collection and
        `null` when it could not, in which case `tick_count` alone reports what
        has been processed. `arguments` are rendered through the task's masking
        rules, so a secret passed as a parameter is stored for reproducibility
        but never echoed back.


        **Required scope:** `read_maintenance_tasks` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const run = await client.maintenanceTaskRuns.get('mtr_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /maintenance_task_runs/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: maintenance task run found
          content:
            application/json:
              example:
                id: mtr_UkLWZg9DAJ
                status: running
                dry_run: false
                initiated_via: api
                tick_count: 5
                tick_total: 20
                error_class:
                error_message:
                started_at:
                ended_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                task_name: capture_methods
                duration: 0.0
                tallies: {}
                arguments: {}
                error_backtrace:
                active: true
                admin_user_id:
              schema:
                "$ref": "#/components/schemas/MaintenanceTaskRun"
        '404':
          description: maintenance task run not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Maintenance task run not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/admin/maintenance_task_runs/{maintenance_task_run_id}/cancellation":
    parameters:
    - name: maintenance_task_run_id
      in: path
      description: Maintenance task run ID
      required: true
      schema:
        type: string
    post:
      summary: Cancel a maintenance task run
      tags:
      - Maintenance Tasks
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Asks the runner to stop for good at its next checkpoint.

        Cancelling is not a rollback — work already committed stays committed.
        What a cancelled run keeps is its cursor, so an operator can see how
        far it got. A run that is still `cancelling` because its worker has
        gone is cancelled outright by a second request.


        **Required scope:** `write_maintenance_tasks` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const run = await client.maintenanceTaskRuns.cancel('mtr_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api post /maintenance_task_runs/{maintenance_task_run_id}/cancellation
          -d '{ ... }'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: maintenance task run cancelling
          content:
            application/json:
              example:
                id: mtr_UkLWZg9DAJ
                status: cancelling
                dry_run: false
                initiated_via: api
                tick_count: 0
                tick_total:
                error_class:
                error_message:
                started_at:
                ended_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                task_name: capture_methods
                duration: 0.0
                tallies: {}
                arguments: {}
                error_backtrace:
                active: true
                admin_user_id:
              schema:
                "$ref": "#/components/schemas/MaintenanceTaskRun"
        '422':
          description: maintenance task run cannot be cancelled
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: a run with status succeeded cannot be cancelled
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/admin/markets":
    get:
      summary: List markets
      tags:
      - Markets
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the markets configured for the current store. Markets are
        store-scoped and ordered by `position` (an `acts_as_list` column —
        update the order via `PATCH /markets/{id}` with `position`).


        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: markets } = await client.markets.list()
      - lang: bash
        label: Spree CLI
        source: spree api get /markets
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of name (partial, case-insensitive).
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      - name: sort
        in: query
        required: false
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: 'Comma-separated associations to embed. Supported: `countries`.'
        schema:
          type: string
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `currency` | One of the `CurrencyCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `default_locale` | One of the `LocaleCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `currency`, `default_locale`, `id`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Market
        sortable:
        - created_at
        - currency
        - default_locale
        - id
        - name
        - position
        - updated_at
      responses:
        '200':
          description: markets found
          content:
            application/json:
              example:
                data:
                - id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  tax_provider:
                - id: mkt_gbHJdmfrXB
                  name: EU
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: false
                  country_codes:
                  - DE
                  supported_locales:
                  - en
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  tax_provider:
                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/Market"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
    post:
      summary: Create a market
      tags:
      - Markets
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Creates a new market for the current store.

        - `country_codes` accepts 2-letter ISO country codes (e.g. `["DE", "FR"]`);
          the market must contain at least one country. Unknown codes are
          silently dropped.
        - `supported_locales` accepts an array of locale codes; the
          `default_locale` is always implicitly included.
        - Setting `default: true` automatically demotes the previous default
          market in the store.


        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const market = await client.markets.create({
            name: 'Europe',
            currency: 'EUR',
            default_locale: 'de',
            supported_locales: ['de', 'en', 'fr'],
            tax_inclusive: true,
            country_codes: ['DE', 'FR', 'IT'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /markets -d '{"name":"Europe","currency":"EUR","default_locale":"de","supported_locales":["de","en","fr"],"tax_inclusive":true,"country_codes":["DE","FR","IT"]}'
      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: market created
          content:
            application/json:
              example:
                id: mkt_EfhxLZ9ck8
                name: France only
                currency: EUR
                default_locale: fr
                tax_inclusive: true
                default: false
                country_codes:
                - FR
                supported_locales:
                - en
                - fr
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                tax_provider:
              schema:
                "$ref": "#/components/schemas/Market"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Name can't be blank, Currency can't be blank, Default locale
                    can't be blank, and Countries can't be blank
                  details:
                    name:
                    - code: blank
                      message: can't be blank
                      specific: false
                    currency:
                    - code: blank
                      message: can't be blank
                      specific: false
                    default_locale:
                    - code: blank
                      message: can't be blank
                      specific: false
                    countries:
                    - code: blank
                      message: can't be blank
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MarketCreateParams"
        required: true
  "/api/v3/admin/markets/{id}":
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      summary: Get a market
      tags:
      - Markets
      security:
      - api_key: []
        bearer_auth: []
      description: "**Required scope:** `read_settings` (for API-key authentication)."
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const market = await client.markets.get('market_xxx')
      - lang: bash
        label: Spree CLI
        source: spree api get /markets/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: expand
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: market found
          content:
            application/json:
              example:
                id: mkt_gbHJdmfrXB
                name: EU
                currency: USD
                default_locale: en
                tax_inclusive: false
                default: false
                country_codes:
                - DE
                supported_locales:
                - en
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                tax_provider:
              schema:
                "$ref": "#/components/schemas/Market"
        '404':
          description: market not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Market not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update a market
      tags:
      - Markets
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Updates an existing market. Pass `country_codes` to replace the
        market's country list (full-set update), `supported_locales` to
        replace the supported locales, or `position` to reorder the market
        within the store.

        Setting `default: true` automatically demotes the previous default.


        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // `country_codes` is a full-set update — the market is reconciled to match
          // the array (adds new countries, removes ones not present). Setting
          // `default: true` demotes the previous default market in the store.
          const market = await client.markets.update('market_UkLWZg9DAJ', {
            name: 'European Union',
            tax_inclusive: true,
            country_codes: ['DE', 'FR'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /markets/{id} -d '{"name":"European Union","tax_inclusive":true,"country_codes":["DE","FR"]}'
      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: market updated
          content:
            application/json:
              example:
                id: mkt_gbHJdmfrXB
                name: European Union
                currency: USD
                default_locale: en
                tax_inclusive: true
                default: false
                country_codes:
                - DE
                supported_locales:
                - en
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                tax_provider:
              schema:
                "$ref": "#/components/schemas/Market"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Name can't be blank
                  details:
                    name:
                    - code: blank
                      message: can't be blank
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MarketUpdateParams"
        required: true
    delete:
      summary: Delete a market
      tags:
      - Markets
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Soft-deletes the market (sets `deleted_at`). The default market and
        the last remaining market in a store cannot be deleted — both return
        422 with a `validation_error`.


        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Soft-deletes the market (sets `deleted_at`). The default market and the
          // last remaining market in a store cannot be deleted — both return 422.
          await client.markets.delete('market_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /markets/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '204':
          description: market deleted
        '422':
          description: cannot delete default or last market
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Market cannot be deleted
  "/api/v3/admin/option_types/{option_type_id}/custom_fields":
    get:
      summary: List option type custom fields
      tags:
      - Option Types
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the option type's custom field values.

        **Required scope:** `read_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: customFields } = await client.optionTypes.customFields.list('opt_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /option_types/{option_type_id}/custom_fields
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: option_type_id
        in: path
        required: true
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., custom_field_definition).
          Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., key,value,namespace).
          id is always included.
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: CustomField
        sortable:
        - created_at
        - id
        - updated_at
      responses:
        '200':
          description: custom fields found
          content:
            application/json:
              example:
                data:
                - id: cf_UkLWZg9DAJ
                  label: Title
                  field_type: short_text
                  key: custom.title
                  value: wool
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  storefront_visible: true
                  custom_field_definition_id: cfdef_UkLWZg9DAJ
                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/CustomField"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
  "/api/v3/admin/option_types":
    get:
      summary: List option types
      tags:
      - Option Types
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a paginated list of option types.

        **Required scope:** `read_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: optionTypes } = await client.optionTypes.list()
      - lang: bash
        label: Spree CLI
        source: spree api get /option_types
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of name and label (partial, case-insensitive).
      - name: q[search_by_name]
        in: query
        required: false
        schema:
          type: string
        description: Applies `search_by_name` to the given value.
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., option_values).
          Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,label,position).
          id is always included.
        schema:
          type: string
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `kind` | One of `dropdown`, `color_swatch`, `buttons` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `label` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: OptionType
        sortable:
        - created_at
        - id
        - kind
        - label
        - name
        - position
        - updated_at
      responses:
        '200':
          description: option types found
          content:
            application/json:
              example:
                data:
                - id: opt_UkLWZg9DAJ
                  name: foo-size-14
                  label: Size
                  position: 1
                  kind: dropdown
                  metadata: {}
                  filterable: true
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                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/OptionType"
                  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"
    post:
      summary: Create an option type
      tags:
      - Option Types
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Creates a new option type. Supports nested option values.

        Option values can be provided inline and will be created or updated by name.


        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const optionType = await client.optionTypes.create({
            name: 'color',
            label: 'Color',
            option_values: [
              { name: 'red', label: 'Red' },
              { name: 'navy', label: 'Navy' },
            ],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /option_types -d '{"name":"color","label":"Color","option_values":[{"name":"red","label":"Red"},{"name":"navy","label":"Navy"}]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '201':
          description: option type created
          content:
            application/json:
              example:
                id: opt_gbHJdmfrXB
                name: material
                label: Material
                position: 2
                kind: dropdown
                metadata: {}
                filterable: true
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/OptionType"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Name can't be blank and Label can't be blank
                  details:
                    name:
                    - code: blank
                      message: can't be blank
                      specific: false
                    label:
                    - code: blank
                      message: can't be blank
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/OptionTypeCreateParams"
        required: true
  "/api/v3/admin/option_types/{id}":
    get:
      summary: Get an option type
      tags:
      - Option Types
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a single option type by ID, including its option values.

        **Required scope:** `read_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const optionType = await client.optionTypes.get('ot_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /option_types/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Option type ID
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., option_values).
          Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,label,position).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: option type found
          content:
            application/json:
              example:
                id: opt_UkLWZg9DAJ
                name: foo-size-18
                label: Size
                position: 1
                kind: dropdown
                metadata: {}
                filterable: true
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/OptionType"
        '404':
          description: option type not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Option type not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update an option type
      tags:
      - Option Types
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Updates an option type. Supports updating nested option values.

        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const optionType = await client.optionTypes.update('ot_UkLWZg9DAJ', {
            label: 'Updated Label',
            option_values: [{ name: 'red', label: 'Crimson' }],
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /option_types/{id} -d '{"label":"Updated Label","option_values":[{"name":"red","label":"Crimson"}]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Option type ID
        schema:
          type: string
      responses:
        '200':
          description: option type updated
          content:
            application/json:
              example:
                id: opt_UkLWZg9DAJ
                name: foo-size-20
                label: Updated Label
                position: 1
                kind: dropdown
                metadata: {}
                filterable: true
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/OptionType"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Label can't be blank
                  details:
                    label:
                    - code: blank
                      message: can't be blank
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/OptionTypeUpdateParams"
        required: true
    delete:
      summary: Delete an option type
      tags:
      - Option Types
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Deletes an option type.

        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.optionTypes.delete('ot_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /option_types/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Option type ID
        schema:
          type: string
      responses:
        '204':
          description: option type deleted
  "/api/v3/admin/claims":
    get:
      summary: List claims
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Every damage or missing-item claim in the store, across all orders.

        **Required scope:** `read_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: claims } = await client.claims.list({
            status_eq: 'open',
            sort: '-created_at',
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /claims -d '{"status_eq":"open","sort":"-created_at"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of number (partial, case-insensitive).
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `status` | One of `open`, `approved`, `resolved`, `denied`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
          | `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
          | `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
          | `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
          | `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
          | `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
          | `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
          | `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
          | `order_store_` | `created_at`, `id`, `name`, `updated_at` |
          | `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
          | `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |

          </Accordion>

          **Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Claim
        sortable:
        - created_at
        - id
        - number
        - status
        - updated_at
      responses:
        '200':
          description: claims listed
          content:
            application/json:
              example:
                data:
                - id: claim_UkLWZg9DAJ
                  number: CLM1001
                  status: open
                  resolution:
                  order_id: or_UkLWZg9DAJ
                  reason_id:
                  refund_total: '10.00'
                  approved_at:
                  resolved_at:
                  denied_at:
                  canceled_at:
                  memo: Arrived with a cracked screen
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  created_by_id:
                  created_by_type:
                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/Claim"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
  "/api/v3/admin/orders/{order_id}/claims":
    get:
      summary: List order claims
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        The damage or missing-item claims opened on one order.

        **Required scope:** `read_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: claims } = await client.orders.claims.list('or_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /orders/{order_id}/claims
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of number (partial, case-insensitive).
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `status` | One of `open`, `approved`, `resolved`, `denied`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
          | `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
          | `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
          | `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
          | `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
          | `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
          | `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
          | `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
          | `order_store_` | `created_at`, `id`, `name`, `updated_at` |
          | `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
          | `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |

          </Accordion>

          **Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Claim
        sortable:
        - created_at
        - id
        - number
        - status
        - updated_at
      responses:
        '200':
          description: claims listed
          content:
            application/json:
              example:
                data:
                - id: claim_UkLWZg9DAJ
                  number: CLM1001
                  status: open
                  resolution:
                  order_id: or_UkLWZg9DAJ
                  reason_id:
                  refund_total: '10.00'
                  approved_at:
                  resolved_at:
                  denied_at:
                  canceled_at:
                  memo: Arrived with a cracked screen
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  created_by_id:
                  created_by_type:
                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/Claim"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
    post:
      summary: Create a claim
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Opens a damage or missing-item claim on a completed order. Each item says how it should be made right: money back, a replacement, or both.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // The customer keeps the goods: nothing comes back, so no return is opened.
          const claim = await client.orders.claims.create('or_UkLWZg9DAJ', {
            reason_id: 'clr_UkLWZg9DAJ',
            memo: 'Arrived with a cracked lid',
            items: [
              {
                line_item_id: 'li_UkLWZg9DAJ',
                quantity: 1,
                description: 'Lid cracked in transit',
                send_replacement: true,
              },
            ],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /orders/{order_id}/claims -d '{"reason_id":"clr_UkLWZg9DAJ","memo":"Arrived
          with a cracked lid","items":[{"line_item_id":"li_UkLWZg9DAJ","quantity":1,"description":"Lid
          cracked in transit","send_replacement":true}]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      responses:
        '201':
          description: claim opened
          content:
            application/json:
              example:
                id: claim_gbHJdmfrXB
                number: CLM1002
                status: open
                resolution:
                order_id: or_gbHJdmfrXB
                reason_id:
                refund_total: '10.00'
                approved_at:
                resolved_at:
                denied_at:
                canceled_at:
                memo: Arrived cracked
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                created_by_id: adm_UkLWZg9DAJ
                created_by_type: admin_user
              schema:
                "$ref": "#/components/schemas/Claim"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ClaimCreateParams"
        required: true
  "/api/v3/admin/orders/{order_id}/claims/{id}":
    patch:
      summary: Update a claim
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Edits the reason, memo or metadata of a claim. Its status moves only through the approve, resolve, deny and cancel actions.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const claim = await client.orders.claims.update('or_UkLWZg9DAJ', 'claim_UkLWZg9DAJ', {
            memo: 'Photos received from the customer',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/claims/{id} -d '{"memo":"Photos
          received from the customer"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Claim prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: claim updated
          content:
            application/json:
              example:
                id: claim_UkLWZg9DAJ
                number: CLM1001
                status: open
                resolution:
                order_id: or_UkLWZg9DAJ
                reason_id: clr_UkLWZg9DAJ
                refund_total: '10.00'
                approved_at:
                resolved_at:
                denied_at:
                canceled_at:
                memo: Customer sent photos
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                created_by_id:
                created_by_type:
              schema:
                "$ref": "#/components/schemas/Claim"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ClaimUpdateParams"
        required: true
  "/api/v3/admin/orders/{order_id}/claims/{id}/approve":
    patch:
      summary: Approve a claim
      tags:
      - Orders
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const claim = await client.orders.claims.approve('or_UkLWZg9DAJ', 'claim_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/claims/{id}/approve -d '{ ... }'
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Accepts an open claim, the step before resolving it with a refund, a replacement or both. Only an open claim can be approved; deny it to turn it down.

        **Required scope:** `write_orders` (for API-key authentication).
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Claim prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: claim approved
          content:
            application/json:
              example:
                id: claim_UkLWZg9DAJ
                number: CLM1001
                status: approved
                resolution:
                order_id: or_UkLWZg9DAJ
                reason_id:
                refund_total: '10.00'
                approved_at: '2026-01-15T12:00:00Z'
                resolved_at:
                denied_at:
                canceled_at:
                memo: Arrived with a cracked screen
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                created_by_id: adm_UkLWZg9DAJ
                created_by_type: admin_user
              schema:
                "$ref": "#/components/schemas/Claim"
  "/api/v3/admin/orders/{order_id}/claims/{id}/resolve":
    patch:
      summary: Resolve a claim
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Settles an approved claim with money back, a replacement shipment, or both.

        **Required scope:** `write_orders`, plus `write_refunds` for a resolution that refunds (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const claim = await client.orders.claims.resolve('or_UkLWZg9DAJ', 'claim_UkLWZg9DAJ', {
            resolution: 'refund_and_replacement',
            refund_method: 'original_payment',
            amount: '5.00',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/claims/{id}/resolve -d '{"resolution":"refund_and_replacement","refund_method":"original_payment","amount":"5.00"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Claim prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: claim resolved
          content:
            application/json:
              example:
                id: claim_UkLWZg9DAJ
                number: CLM1001
                status: resolved
                resolution: refund
                order_id: or_UkLWZg9DAJ
                reason_id:
                refund_total: '10.00'
                approved_at: '2026-01-15T12:00:00Z'
                resolved_at: '2026-01-15T12:00:00Z'
                denied_at:
                canceled_at:
                memo: Arrived with a cracked screen
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                created_by_id:
                created_by_type:
              schema:
                "$ref": "#/components/schemas/Claim"
        '422':
          description: unknown resolution
          content:
            application/json:
              example:
                error:
                  code: processing_error
                  message: Invalid resolution
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ClaimResolveParams"
        required: true
  "/api/v3/admin/orders/{order_id}/claims/{id}/deny":
    patch:
      summary: Deny a claim
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Turns down an open claim, recording why for the customer.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const claim = await client.orders.claims.deny('or_UkLWZg9DAJ', 'claim_UkLWZg9DAJ', {
            reason: 'Damage is not covered after 30 days',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/claims/{id}/deny -d '{"reason":"Damage
          is not covered after 30 days"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Claim prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: claim denied
          content:
            application/json:
              example:
                id: claim_UkLWZg9DAJ
                number: CLM1001
                status: denied
                resolution:
                order_id: or_UkLWZg9DAJ
                reason_id:
                refund_total: '10.00'
                approved_at:
                resolved_at:
                denied_at: '2026-01-15T12:00:00Z'
                canceled_at:
                memo: |-
                  Arrived with a cracked screen
                  Outside warranty
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                created_by_id:
                created_by_type:
              schema:
                "$ref": "#/components/schemas/Claim"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ClaimDenyParams"
  "/api/v3/admin/orders/{order_id}/claims/{id}/cancel":
    patch:
      summary: Cancel a claim
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Withdraws a claim that has not been resolved.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const claim = await client.orders.claims.cancel('or_UkLWZg9DAJ', 'claim_UkLWZg9DAJ', {
            reason: 'Opened by mistake',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/claims/{id}/cancel -d '{"reason":"Opened
          by mistake"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Claim prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: claim canceled
          content:
            application/json:
              example:
                id: claim_UkLWZg9DAJ
                number: CLM1001
                status: canceled
                resolution:
                order_id: or_UkLWZg9DAJ
                reason_id:
                refund_total: '10.00'
                approved_at:
                resolved_at:
                denied_at:
                canceled_at: '2026-01-15T12:00:00Z'
                memo: |-
                  Arrived with a cracked screen
                  Customer found the missing item
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                created_by_id:
                created_by_type:
              schema:
                "$ref": "#/components/schemas/Claim"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ClaimCancelParams"
  "/api/v3/admin/orders/{order_id}/custom_fields":
    get:
      summary: List order custom fields
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the order's custom field values.

        **Required scope:** `read_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: customFields } = await client.orders.customFields.list('or_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /orders/{order_id}/custom_fields
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., custom_field_definition).
          Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., key,value,namespace).
          id is always included.
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: CustomField
        sortable:
        - created_at
        - id
        - updated_at
      responses:
        '200':
          description: custom fields found
          content:
            application/json:
              example:
                data:
                - id: cf_UkLWZg9DAJ
                  label: Title
                  field_type: short_text
                  key: custom.title
                  value: wool
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  storefront_visible: true
                  custom_field_definition_id: cfdef_UkLWZg9DAJ
                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/CustomField"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
  "/api/v3/admin/digital_links":
    get:
      summary: List digital links
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the download links issued for digital products bought in this store, newest first.

        **Required scope:** `read_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: digitalLinks } = await client.digitalLinks.list({
            sort: '-created_at',
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /digital_links -d '{"sort":"-created_at"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: DigitalLink
        sortable:
        - created_at
        - id
        - updated_at
      responses:
        '200':
          description: digital links found
          content:
            application/json:
              example:
                data:
                - id: dl_UkLWZg9DAJ
                  access_counter: 0
                  filename: thinking-cat.jpg
                  content_type: image/jpeg
                  download_url: "/api/v3/store/digital_links/Sh7B5YVQvB8N7t2mhgUnL9Lv"
                  expires_at: '2026-01-22T12:00:00Z'
                  authorizable: true
                  expired: false
                  access_limit_exceeded: false
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                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/DigitalLink"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
  "/api/v3/admin/digital_links/{id}":
    parameters:
    - name: id
      in: path
      required: true
      description: Digital link ID
      schema:
        type: string
    get:
      summary: Get a digital link
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a single download link with its download count and expiry.

        **Required scope:** `read_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const digitalLink = await client.digitalLinks.retrieve('dl_xxx')
      - lang: bash
        label: Spree CLI
        source: spree api get /digital_links/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: digital link found
          content:
            application/json:
              example:
                id: dl_UkLWZg9DAJ
                access_counter: 0
                filename: thinking-cat.jpg
                content_type: image/jpeg
                download_url: "/api/v3/store/digital_links/ks9F16gjTLQPCzwFDpj2ifrJ"
                expires_at: '2026-01-22T12:00:00Z'
                authorizable: true
                expired: false
                access_limit_exceeded: false
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/DigitalLink"
        '404':
          description: digital link not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Digital link not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/admin/digital_links/{id}/reset":
    parameters:
    - name: id
      in: path
      required: true
      description: Digital link ID
      schema:
        type: string
    patch:
      summary: Reset a digital link
      tags:
      - Orders
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const digitalLink = await client.digitalLinks.reset('dl_xxx')
      - lang: bash
        label: Spree CLI
        source: spree api patch /digital_links/{id}/reset -d '{ ... }'
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Gives the customer their full download allowance back and restarts the
        link's expiry clock. Use it when a download failed, or the file was
        replaced after the customer had used up their attempts.


        **Required scope:** `write_orders` (for API-key authentication).
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: digital link reset
          content:
            application/json:
              example:
                id: dl_UkLWZg9DAJ
                access_counter: 0
                filename: thinking-cat.jpg
                content_type: image/jpeg
                download_url: "/api/v3/store/digital_links/tPqch4JvZidezkNn2YoqxDLc"
                expires_at: '2026-01-22T12:00:00Z'
                authorizable: true
                expired: false
                access_limit_exceeded: false
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/DigitalLink"
  "/api/v3/admin/exchanges":
    get:
      summary: List exchanges
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Every exchange in the store, across all orders.

        **Required scope:** `read_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: exchanges } = await client.exchanges.list({
            status_eq: 'received',
            sort: '-created_at',
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /exchanges -d '{"status_eq":"received","sort":"-created_at"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of number (partial, case-insensitive).
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `status` | One of `requested`, `approved`, `received`, `fulfilled`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
          | `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
          | `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
          | `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
          | `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
          | `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
          | `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
          | `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
          | `order_store_` | `created_at`, `id`, `name`, `updated_at` |
          | `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
          | `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |

          </Accordion>

          **Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Exchange
        sortable:
        - created_at
        - id
        - number
        - status
        - updated_at
      responses:
        '200':
          description: exchanges listed
          content:
            application/json:
              example:
                data:
                - id: exch_UkLWZg9DAJ
                  number: EX1001
                  status: requested
                  order_id: or_UkLWZg9DAJ
                  reason_id:
                  price_difference: '9.99'
                  approved_at:
                  received_at:
                  fulfilled_at:
                  canceled_at:
                  memo: Wrong size
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  stock_location_id: sloc_UkLWZg9DAJ
                  created_by_id:
                  created_by_type:
                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/Exchange"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
  "/api/v3/admin/orders/{order_id}/exchanges":
    get:
      summary: List order exchanges
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        The exchanges opened on one order.

        **Required scope:** `read_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: exchanges } = await client.orders.exchanges.list('or_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /orders/{order_id}/exchanges
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of number (partial, case-insensitive).
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `status` | One of `requested`, `approved`, `received`, `fulfilled`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
          | `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
          | `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
          | `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
          | `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
          | `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
          | `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
          | `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
          | `order_store_` | `created_at`, `id`, `name`, `updated_at` |
          | `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
          | `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |

          </Accordion>

          **Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Exchange
        sortable:
        - created_at
        - id
        - number
        - status
        - updated_at
      responses:
        '200':
          description: exchanges listed
          content:
            application/json:
              example:
                data:
                - id: exch_UkLWZg9DAJ
                  number: EX1001
                  status: requested
                  order_id: or_UkLWZg9DAJ
                  reason_id:
                  price_difference: '9.99'
                  approved_at:
                  received_at:
                  fulfilled_at:
                  canceled_at:
                  memo: Wrong size
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  stock_location_id: sloc_UkLWZg9DAJ
                  created_by_id:
                  created_by_type:
                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/Exchange"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
    post:
      summary: Create an exchange
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Opens an exchange on a completed order: items coming back, and the variant that goes out in place of each.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const exchange = await client.orders.exchanges.create('or_UkLWZg9DAJ', {
            reason_id: 'rar_UkLWZg9DAJ',
            stock_location_id: 'sloc_UkLWZg9DAJ',
            items: [
              { fulfillment_item_id: 'fi_UkLWZg9DAJ', new_variant_id: 'variant_k5nR8xLq', quantity: 1 },
            ],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /orders/{order_id}/exchanges -d '{"reason_id":"rar_UkLWZg9DAJ","stock_location_id":"sloc_UkLWZg9DAJ","items":[{"fulfillment_item_id":"fi_UkLWZg9DAJ","new_variant_id":"variant_k5nR8xLq","quantity":1}]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      responses:
        '201':
          description: exchange opened
          content:
            application/json:
              example:
                id: exch_gbHJdmfrXB
                number: EX1002
                status: requested
                order_id: or_gbHJdmfrXB
                reason_id:
                price_difference: '9.99'
                approved_at:
                received_at:
                fulfilled_at:
                canceled_at:
                memo: Wrong size
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                stock_location_id: sloc_UkLWZg9DAJ
                created_by_id: adm_UkLWZg9DAJ
                created_by_type: admin_user
              schema:
                "$ref": "#/components/schemas/Exchange"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ExchangeCreateParams"
        required: true
  "/api/v3/admin/orders/{order_id}/exchanges/{id}":
    patch:
      summary: Update an exchange
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Edits the warehouse, reason, memo or metadata of an exchange. Its status moves only through the approve, receive, fulfill and cancel actions.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const exchange = await client.orders.exchanges.update('or_UkLWZg9DAJ', 'exch_UkLWZg9DAJ', {
            memo: 'Customer prefers the larger size',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/exchanges/{id} -d '{"memo":"Customer
          prefers the larger size"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Exchange prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: exchange updated
          content:
            application/json:
              example:
                id: exch_UkLWZg9DAJ
                number: EX1001
                status: requested
                order_id: or_UkLWZg9DAJ
                reason_id: rar_UkLWZg9DAJ
                price_difference: '9.99'
                approved_at:
                received_at:
                fulfilled_at:
                canceled_at:
                memo: Customer wants a larger size
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                stock_location_id: sloc_UkLWZg9DAJ
                created_by_id:
                created_by_type:
              schema:
                "$ref": "#/components/schemas/Exchange"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ExchangeUpdateParams"
        required: true
  "/api/v3/admin/orders/{order_id}/exchanges/{id}/approve":
    patch:
      summary: Approve an exchange
      tags:
      - Orders
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const exchange = await client.orders.exchanges.approve('or_UkLWZg9DAJ', 'exch_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/exchanges/{id}/approve -d '{ ...
          }'
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Accepts a requested exchange so the customer can send the goods back for their replacement. Only a requested exchange can be approved; receive it once the goods arrive.

        **Required scope:** `write_orders` (for API-key authentication).
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Exchange prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: exchange approved
          content:
            application/json:
              example:
                id: exch_UkLWZg9DAJ
                number: EX1001
                status: approved
                order_id: or_UkLWZg9DAJ
                reason_id:
                price_difference: '9.99'
                approved_at: '2026-01-15T12:00:00Z'
                received_at:
                fulfilled_at:
                canceled_at:
                memo: Wrong size
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                stock_location_id: sloc_UkLWZg9DAJ
                created_by_id: adm_UkLWZg9DAJ
                created_by_type: admin_user
              schema:
                "$ref": "#/components/schemas/Exchange"
        '422':
          description: the exchange is not requested
          content:
            application/json:
              example:
                error:
                  code: processing_error
                  message: Not requested
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/admin/orders/{order_id}/exchanges/{id}/receive":
    patch:
      summary: Receive an exchange
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Records the goods that came back on an approved exchange. Omit `items` to receive everything as requested and resellable.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Omit `items` to receive everything as requested and resellable.
          const exchange = await client.orders.exchanges.receive('or_UkLWZg9DAJ', 'exch_UkLWZg9DAJ', {
            items: [{ exchange_line_item_id: 'eli_UkLWZg9DAJ', quantity: 1, resellable: false }],
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/exchanges/{id}/receive -d '{"items":[{"exchange_line_item_id":"eli_UkLWZg9DAJ","quantity":1,"resellable":false}]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Exchange prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: exchange received
          content:
            application/json:
              example:
                id: exch_UkLWZg9DAJ
                number: EX1001
                status: received
                order_id: or_UkLWZg9DAJ
                reason_id:
                price_difference: '9.99'
                approved_at: '2026-01-15T12:00:00Z'
                received_at: '2026-01-15T12:00:00Z'
                fulfilled_at:
                canceled_at:
                memo: Wrong size
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                stock_location_id: sloc_UkLWZg9DAJ
                created_by_id:
                created_by_type:
              schema:
                "$ref": "#/components/schemas/Exchange"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ExchangeReceiveParams"
  "/api/v3/admin/orders/{order_id}/exchanges/{id}/fulfill":
    patch:
      summary: Fulfill an exchange
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Ships the replacements for a received exchange and settles any price difference.

        **Required scope:** `write_orders` and `write_refunds` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const exchange = await client.orders.exchanges.fulfill('or_UkLWZg9DAJ', 'exch_UkLWZg9DAJ', {
            refund_method: 'store_credit',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/exchanges/{id}/fulfill -d '{"refund_method":"store_credit"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Exchange prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: exchange fulfilled
          content:
            application/json:
              example:
                id: exch_UkLWZg9DAJ
                number: EX1001
                status: fulfilled
                order_id: or_UkLWZg9DAJ
                reason_id:
                price_difference: '9.99'
                approved_at: '2026-01-14T12:00:00Z'
                received_at: '2026-01-15T12:00:00Z'
                fulfilled_at: '2026-01-15T12:00:00Z'
                canceled_at:
                memo: Wrong size
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                stock_location_id: sloc_UkLWZg9DAJ
                created_by_id:
                created_by_type:
              schema:
                "$ref": "#/components/schemas/Exchange"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ExchangeFulfillParams"
  "/api/v3/admin/orders/{order_id}/exchanges/{id}/cancel":
    patch:
      summary: Cancel an exchange
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Withdraws an exchange whose goods have not been received.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const exchange = await client.orders.exchanges.cancel('or_UkLWZg9DAJ', 'exch_UkLWZg9DAJ', {
            reason: 'Customer kept the original item',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/exchanges/{id}/cancel -d '{"reason":"Customer
          kept the original item"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Exchange prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: exchange canceled
          content:
            application/json:
              example:
                id: exch_UkLWZg9DAJ
                number: EX1001
                status: canceled
                order_id: or_UkLWZg9DAJ
                reason_id:
                price_difference: '9.99'
                approved_at:
                received_at:
                fulfilled_at:
                canceled_at: '2026-01-15T12:00:00Z'
                memo: |-
                  Wrong size
                  Customer kept the original
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                stock_location_id: sloc_UkLWZg9DAJ
                created_by_id:
                created_by_type:
              schema:
                "$ref": "#/components/schemas/Exchange"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ExchangeCancelParams"
  "/api/v3/admin/orders/{order_id}/tax_lines":
    get:
      summary: List tax lines
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Typed tax rows on the order. Read-only — written exclusively by the tax provider.

        **Required scope:** `read_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: taxLines } = await client.orders.taxLines.list('or_abc123')
      - lang: bash
        label: Spree CLI
        source: spree api get /orders/{order_id}/tax_lines
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[provider_id_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `country_code` | One of the `CountryCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `included` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
          | `provider_id` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `taxability_reason` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `country_code`, `created_at`, `id`, `included`, `provider_id`, `state_code`, `taxability_reason`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: TaxLine
        sortable:
        - country_code
        - created_at
        - id
        - included
        - provider_id
        - state_code
        - taxability_reason
        - updated_at
      responses:
        '200':
          description: tax lines found
          content:
            application/json:
              example:
                data:
                - id: tl_UkLWZg9DAJ
                  label: VAT 15%
                  included: false
                  credit: false
                  rate: '0.15'
                  tax_rate_id:
                  line_item_id: li_UkLWZg9DAJ
                  fulfillment_id:
                  fee_id:
                  return_line_item_id:
                  claim_line_item_id:
                  exchange_line_item_id:
                  amount: '1.50'
                  provider_id: internal
                  metadata: {}
                  taxability_reason:
                  country_code:
                  state_code:
                  data: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  original_tax_line_id:
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
  "/api/v3/admin/orders/{order_id}/discounts":
    get:
      summary: List discounts
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Typed discount rows (promotion-sourced and manual) on the order.

        **Required scope:** `read_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: discounts } = await client.orders.discounts.list('or_abc123')
      - lang: bash
        label: Spree CLI
        source: spree api get /orders/{order_id}/discounts
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Discount
        sortable:
        - created_at
        - id
        - updated_at
      responses:
        '200':
          description: discounts found
          content:
            application/json:
              example:
                data:
                - id: disc_UkLWZg9DAJ
                  label: Loyalty
                  kind: manual
                  code:
                  value_type:
                  value:
                  promotion_id:
                  line_item_id: li_UkLWZg9DAJ
                  fulfillment_id:
                  amount: "-2.00"
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
    post:
      summary: Create manual discount
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Creates a manual discount. With line_item_id a single row is created; without it the amount is distributed across line items (largest remainder). This is the sanctioned post-placement discount path and works on completed orders.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Line-item discount; omit line_item_id to distribute across the order.
          const { data: discounts } = await client.orders.discounts.create('or_abc123', {
            label: 'Customer appeasement',
            value: '10',
            value_type: 'flat',
            line_item_id: 'item_abc123',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /orders/{order_id}/discounts -d '{"label":"Customer
          appeasement","value":"10","value_type":"flat","line_item_id":"item_abc123"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      responses:
        '201':
          description: discount created
          content:
            application/json:
              example:
                data:
                - id: disc_UkLWZg9DAJ
                  label: Appeasement
                  kind: manual
                  code:
                  value_type: flat
                  value: '3.00'
                  promotion_id:
                  line_item_id: li_UkLWZg9DAJ
                  fulfillment_id:
                  amount: "-3.00"
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
        '422':
          description: invalid discount
          content:
            application/json:
              example:
                error:
                  code: invalid_money_format
                  message: value must be a decimal string like "19.99"
                  details:
                    value:
                    - must be a decimal string like "19.99"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/DiscountCreateParams"
        required: true
  "/api/v3/admin/orders/{order_id}/discounts/{id}":
    patch:
      summary: Update manual discount
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Edits the label or amount of a manual discount and re-sums the order totals. Promotion-sourced rows are owned by recalculation and respond 422.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const discount = await client.orders.discounts.update('or_UkLWZg9DAJ', 'disc_UkLWZg9DAJ', {
            label: 'Customer appeasement',
            amount: '15.00',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/discounts/{id} -d '{"label":"Customer
          appeasement","amount":"15.00"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Discount prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: discount updated
          content:
            application/json:
              example:
                id: disc_UkLWZg9DAJ
                label: Loyalty reward
                kind: manual
                code:
                value_type:
                value:
                promotion_id:
                line_item_id: li_UkLWZg9DAJ
                fulfillment_id:
                amount: "-5.00"
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/DiscountUpdateParams"
        required: true
  "/api/v3/admin/orders/{order_id}/fees":
    get:
      summary: List fees
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the order's fees, such as surcharges, handling and gift wrap, on the whole order or on one item or delivery.

        **Required scope:** `read_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: fees } = await client.orders.fees.list('or_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /orders/{order_id}/fees
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Fee
        sortable:
        - created_at
        - id
        - updated_at
      responses:
        '200':
          description: fees found
          content:
            application/json:
              example:
                data:
                - id: fee_UkLWZg9DAJ
                  label: Gift wrap
                  kind: gift_wrap
                  line_item_id:
                  fulfillment_id:
                  amount: '4.00'
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                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/Fee"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
    post:
      summary: Create fee
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Creates a fee (surcharge, handling, gift wrap, COD, payment fee). Order-level when no target is given. Works on completed orders.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const fee = await client.orders.fees.create('or_abc123', {
            label: 'Gift wrap',
            amount: '4.00',
            kind: 'gift_wrap',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /orders/{order_id}/fees -d '{"label":"Gift wrap","amount":"4.00","kind":"gift_wrap"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      responses:
        '201':
          description: fee created
          content:
            application/json:
              example:
                id: fee_UkLWZg9DAJ
                label: Gift wrap
                kind: gift_wrap
                line_item_id:
                fulfillment_id:
                amount: '4.00'
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
        '422':
          description: invalid fee
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Kind is not included in the list
                  details:
                    kind:
                    - value: nonsense
                      code: inclusion
                      message: is not included in the list
                      specific: false
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/FeeCreateParams"
        required: true
  "/api/v3/admin/orders/{order_id}/fees/{id}":
    patch:
      summary: Update fee
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Edits the label, amount or kind of a fee and re-sums the order totals. Works on completed orders.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const fee = await client.orders.fees.update('or_UkLWZg9DAJ', 'fee_UkLWZg9DAJ', {
            label: 'Gift wrap',
            amount: '5.00',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/fees/{id} -d '{"label":"Gift wrap","amount":"5.00"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Fee prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: fee updated
          content:
            application/json:
              example:
                id: fee_UkLWZg9DAJ
                label: Handling
                kind: handling
                line_item_id:
                fulfillment_id:
                amount: '8.00'
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/Fee"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/FeeUpdateParams"
        required: true
  "/api/v3/admin/order_groups":
    get:
      summary: List order groups
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns checkouts split into one order per seller, grouping the orders placed together.

        **Required scope:** `read_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: orderGroups } = await client.orderGroups.list({
            email_cont: '[email protected]',
            sort: '-created_at',
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /order_groups -d '{"email_cont":"[email protected]","sort":"-created_at"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `currency` | One of the `CurrencyCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[customer_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
          | `customer_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `customer_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `customer_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |
          | `customer_orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
          | `customer_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `customer_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |
          | `customer_tags_` | `created_at`, `id`, `name`, `updated_at` |
          | `orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
          | `orders_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `orders_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
          | `orders_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
          | `orders_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
          | `orders_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
          | `orders_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
          | `orders_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `orders_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `orders_shipments_` | `created_at`, `id`, `number`, `updated_at` |
          | `orders_store_` | `created_at`, `id`, `name`, `updated_at` |
          | `orders_tags_` | `created_at`, `id`, `name`, `updated_at` |

          </Accordion>

          **Sort by:** `created_at`, `currency`, `email`, `id`, `number`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: OrderGroup
        sortable:
        - created_at
        - currency
        - email
        - id
        - number
        - updated_at
      responses:
        '200':
          description: order groups found
          content:
            application/json:
              example:
                data:
                - id: ogrp_UkLWZg9DAJ
                  number: R1001
                  email: [email protected]
                  currency: USD
                  item_total: '0.00'
                  discount_total: '0.00'
                  tax_total: '0.00'
                  included_tax_total: '0.00'
                  additional_tax_total: '0.00'
                  delivery_total: '0.00'
                  fee_total: '0.00'
                  gift_card_total: '0.00'
                  store_credit_total: '0.00'
                  total: '0.00'
                  amount_due: '0.00'
                  covered_by_store_credit: false
                  payments: []
                  fulfillment_status:
                  payment_status:
                  completed_at: '2026-01-15T12:00:00.000Z'
                  billing_address:
                  shipping_address:
                  orders: []
                  customer_id: cust_UkLWZg9DAJ
                  cart_id:
                  seller_count: 0
                  includes_first_party: false
                  confirmation_delivered: false
                  store_owner_notification_delivered: false
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                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/OrderGroup"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
  "/api/v3/admin/orders/{order_id}/discount_codes":
    post:
      summary: Apply a discount code
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Applies a discount code to a draft order and returns the order. A real code the order does not yet qualify for is kept and applies once it does. Completed orders refuse codes; change their discounts through manual discounts instead.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const order = await client.orders.discountCodes.create('or_UkLWZg9DAJ', {
            code: 'SUMMER20',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /orders/{order_id}/discount_codes -d '{"code":"SUMMER20"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      responses:
        '201':
          description: discount code applied
          content:
            application/json:
              example:
                id: or_UkLWZg9DAJ
                market_id: mkt_UkLWZg9DAJ
                withdrawal_period_ends_at:
                within_withdrawal_period: false
                shipping_eq_billing_address: false
                cart_id:
                channel_id: ch_UkLWZg9DAJ
                company_id:
                company_name:
                po_document_filename:
                po_document_byte_size:
                number: R1001
                email: [email protected]
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                coupon_code: save5
                fulfillment_status:
                payment_status:
                completed_at:
                item_total: '50.00'
                discount_total: "-5.00"
                tax_total: '0.00'
                included_tax_total: '0.00'
                additional_tax_total: '0.00'
                delivery_total: '100.00'
                fee_total: '0.00'
                gift_card_total: '0.00'
                store_credit_total: '0.00'
                total: '145.00'
                amount_due: '145.00'
                covered_by_store_credit: false
                adjustment_total: "-5.00"
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  tax_provider:
                external_references: {}
                status: draft
                last_ip_address:
                considered_risky: false
                confirmation_delivered: false
                store_owner_notification_delivered:
                metadata: {}
                cancel_note:
                canceled_at:
                approved_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                payment_total: '0.00'
                commission_amount_total: '0.00'
                commission_tax_total: '0.00'
                commission_total: '0.00'
                preferred_stock_location_id:
                po_document_url:
                seller_id:
                order_group_id:
                tags: []
                internal_note:
                internal_note_html:
                approver_id:
                approver_type:
                canceler_id:
                canceler_type:
                created_by_id:
                created_by_type:
                cancel_reason_id:
                cancel_reason_name:
                customer_id: cust_UkLWZg9DAJ
                freight_summary:
        '422':
          description: unknown discount code
          content:
            application/json:
              example:
                error:
                  code: processing_error
                  message: The coupon code you entered doesn't exist. Please try again.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/DiscountCodeApplyParams"
        required: true
  "/api/v3/admin/orders/{order_id}/gift_cards":
    post:
      summary: Apply a gift card to an order
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Applies a gift card by code to the order. Returns the gift card.

        **Required scope:** `write_gift_cards` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.orders.giftCards.apply('or_UkLWZg9DAJ', {
            code: 'GIFT-XXXX-YYYY',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /orders/{order_id}/gift_cards -d '{"code":"GIFT-XXXX-YYYY"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      responses:
        '201':
          description: gift card applied
          content:
            application/json:
              example:
                id: gc_UkLWZg9DAJ
                code: "************2F41"
                status: active
                currency: USD
                amount: '10.00'
                amount_used: '10.00'
                amount_authorized: '0.00'
                amount_remaining: '0.00'
                expires_at:
                redeemed_at:
                expired: false
                active: true
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                customer_id:
                created_by_id:
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/GiftCardApplyParams"
        required: true
  "/api/v3/admin/orders/{order_id}/gift_cards/{id}":
    delete:
      summary: Remove a gift card from an order
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Removes the gift card from the order.

        **Required scope:** `write_gift_cards` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.orders.giftCards.remove('or_UkLWZg9DAJ', 'gc_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /orders/{order_id}/gift_cards/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Gift card ID
        schema:
          type: string
      responses:
        '204':
          description: gift card removed
  "/api/v3/admin/orders/{order_id}/items":
    get:
      summary: List order items
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns all line items for an order.

        **Required scope:** `read_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: items } = await client.orders.items.list('or_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /orders/{order_id}/items
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., variant, variant.product).
          Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., quantity,price,total).
          id is always included.
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[additional_tax_total_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `additional_tax_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `adjustment_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `cost_price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `discount_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `included_tax_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `non_taxable_adjustment_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `pre_tax_amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `tax_category_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `taxable_adjustment_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `variant_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
          | `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
          | `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
          | `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
          | `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
          | `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
          | `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
          | `order_store_` | `created_at`, `id`, `name`, `updated_at` |
          | `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
          | `tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
          | `variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |
          | `variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
          | `variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
          | `variant_product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |
          | `variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |

          </Accordion>

          **Sort by:** `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: LineItem
        sortable:
        - additional_tax_total
        - adjustment_total
        - cost_price
        - created_at
        - discount_total
        - id
        - included_tax_total
        - non_taxable_adjustment_total
        - order_id
        - pre_tax_amount
        - price
        - quantity
        - tax_category_id
        - taxable_adjustment_total
        - updated_at
        - variant_id
      responses:
        '200':
          description: items found
          content:
            application/json:
              example:
                data:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_gbHJdmfrXB
                  seller_id:
                  preorder: false
                  preorder_ships_at:
                  quantity: 2
                  currency: USD
                  name: Product 779180
                  slug: product-779180
                  options_text: 'Size: S'
                  price: '10.00'
                  total: '20.00'
                  adjustment_total: '0.00'
                  additional_tax_total: '0.00'
                  included_tax_total: '0.00'
                  discount_total: '0.00'
                  pre_tax_amount: '20.00'
                  discounted_amount: '20.00'
                  compare_at_amount:
                  thumbnail_url:
                  option_values:
                  - id: optval_UkLWZg9DAJ
                    option_type_id: opt_UkLWZg9DAJ
                    name: size-13
                    label: S
                    position: 1
                    color_code:
                    option_type_name: foo-size-23
                    option_type_label: Size
                    image_url:
                    metadata: {}
                    created_at: '2026-01-15T12:00:00.000Z'
                    updated_at: '2026-01-15T12:00:00.000Z'
                  digital_links: []
                  external_references: {}
                  metadata: {}
                  price_source:
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  catalog_price: '19.99'
                  price_list_id:
                  price_list_name:
                  catalog_id:
                  catalog_name:
                  cost_price: '17.00'
                  tax_category_id: taxcat_UkLWZg9DAJ
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
    post:
      summary: Add an item
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Adds a new line item to the order.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const item = await client.orders.items.create('or_UkLWZg9DAJ', {
            variant_id: 'variant_k5nR8xLq',
            quantity: 2,
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /orders/{order_id}/items -d '{"variant_id":"variant_k5nR8xLq","quantity":2}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      responses:
        '201':
          description: item added
          content:
            application/json:
              example:
                id: li_gbHJdmfrXB
                variant_id: variant_VqXmZF31wY
                seller_id:
                preorder: false
                preorder_ships_at:
                quantity: 3
                currency: USD
                name: Product 7999
                slug: product-7999
                options_text: 'Size: S'
                price: '19.99'
                total: '59.97'
                adjustment_total: '0.00'
                additional_tax_total: '0.00'
                included_tax_total: '0.00'
                discount_total: '0.00'
                pre_tax_amount: '59.97'
                discounted_amount: '59.97'
                compare_at_amount:
                thumbnail_url:
                option_values:
                - id: optval_gbHJdmfrXB
                  option_type_id: opt_gbHJdmfrXB
                  name: size-15
                  label: S
                  position: 1
                  color_code:
                  option_type_name: foo-size-25
                  option_type_label: Size
                  image_url:
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                digital_links: []
                external_references: {}
                metadata: {}
                price_source:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                catalog_price: '19.99'
                price_list_id:
                price_list_name:
                catalog_id:
                catalog_name:
                cost_price: '17.00'
                tax_category_id: taxcat_UkLWZg9DAJ
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/LineItemCreateParams"
        required: true
  "/api/v3/admin/orders/{order_id}/items/{id}":
    get:
      summary: Show an item
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns details of a specific line item.

        **Required scope:** `read_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const item = await client.orders.items.get('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /orders/{order_id}/items/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Item ID
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., variant, variant.product).
          Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., quantity,price,total).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: item found
          content:
            application/json:
              example:
                id: li_UkLWZg9DAJ
                variant_id: variant_gbHJdmfrXB
                seller_id:
                preorder: false
                preorder_ships_at:
                quantity: 2
                currency: USD
                name: Product 802714
                slug: product-802714
                options_text: 'Size: S'
                price: '10.00'
                total: '20.00'
                adjustment_total: '0.00'
                additional_tax_total: '0.00'
                included_tax_total: '0.00'
                discount_total: '0.00'
                pre_tax_amount: '20.00'
                discounted_amount: '20.00'
                compare_at_amount:
                thumbnail_url:
                option_values:
                - id: optval_UkLWZg9DAJ
                  option_type_id: opt_UkLWZg9DAJ
                  name: size-16
                  label: S
                  position: 1
                  color_code:
                  option_type_name: foo-size-26
                  option_type_label: Size
                  image_url:
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                digital_links: []
                external_references: {}
                metadata: {}
                price_source:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                catalog_price: '19.99'
                price_list_id:
                price_list_name:
                catalog_id:
                catalog_name:
                cost_price: '17.00'
                tax_category_id: taxcat_UkLWZg9DAJ
    patch:
      summary: Update an item
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Updates an order item quantity or metadata.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const item = await client.orders.items.update('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ', {
            quantity: 5,
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/items/{id} -d '{"quantity":5}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Item ID
        schema:
          type: string
      responses:
        '200':
          description: item updated
          content:
            application/json:
              example:
                id: li_UkLWZg9DAJ
                variant_id: variant_gbHJdmfrXB
                seller_id:
                preorder: false
                preorder_ships_at:
                quantity: 5
                currency: USD
                name: Product 819758
                slug: product-819758
                options_text: 'Size: S'
                price: '19.99'
                total: '99.95'
                adjustment_total: '0.00'
                additional_tax_total: '0.00'
                included_tax_total: '0.00'
                discount_total: '0.00'
                pre_tax_amount: '99.95'
                discounted_amount: '99.95'
                compare_at_amount:
                thumbnail_url:
                option_values:
                - id: optval_UkLWZg9DAJ
                  option_type_id: opt_UkLWZg9DAJ
                  name: size-17
                  label: S
                  position: 1
                  color_code:
                  option_type_name: foo-size-27
                  option_type_label: Size
                  image_url:
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                digital_links: []
                external_references: {}
                metadata: {}
                price_source:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                catalog_price: '19.99'
                price_list_id:
                price_list_name:
                catalog_id:
                catalog_name:
                cost_price: '17.00'
                tax_category_id: taxcat_UkLWZg9DAJ
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/LineItemUpdateParams"
        required: true
    delete:
      summary: Remove an item
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Removes an item from the order.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.orders.items.delete('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /orders/{order_id}/items/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Item ID
        schema:
          type: string
      responses:
        '204':
          description: line item removed
  "/api/v3/admin/orders/{order_id}/store_credits":
    post:
      summary: Apply customer's store credit to an order
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.

        **Required scope:** `write_store_credits` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const order = await client.orders.storeCredits.apply('or_UkLWZg9DAJ', {
            amount: '25.00',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /orders/{order_id}/store_credits -d '{"amount":"25.00"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      responses:
        '201':
          description: store credit applied
          content:
            application/json:
              example:
                id: or_UkLWZg9DAJ
                market_id: mkt_UkLWZg9DAJ
                withdrawal_period_ends_at:
                within_withdrawal_period: false
                shipping_eq_billing_address: false
                cart_id:
                channel_id: ch_UkLWZg9DAJ
                company_id:
                company_name:
                po_document_filename:
                po_document_byte_size:
                number: R1001
                email: [email protected]
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                coupon_code:
                fulfillment_status:
                payment_status:
                completed_at:
                item_total: '10.00'
                discount_total: '0.00'
                tax_total: '0.00'
                included_tax_total: '0.00'
                additional_tax_total: '0.00'
                delivery_total: '100.00'
                fee_total: '0.00'
                gift_card_total: '0.00'
                store_credit_total: '50.00'
                total: '110.00'
                amount_due: '60.00'
                covered_by_store_credit: false
                adjustment_total: '0.00'
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  tax_provider:
                external_references: {}
                status: draft
                last_ip_address:
                considered_risky: false
                confirmation_delivered: false
                store_owner_notification_delivered:
                metadata: {}
                cancel_note:
                canceled_at:
                approved_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                payment_total: '0.00'
                commission_amount_total: '0.00'
                commission_tax_total: '0.00'
                commission_total: '0.00'
                preferred_stock_location_id:
                po_document_url:
                seller_id:
                order_group_id:
                tags: []
                internal_note:
                internal_note_html:
                approver_id:
                approver_type:
                canceler_id:
                canceler_type:
                created_by_id:
                created_by_type:
                cancel_reason_id:
                cancel_reason_name:
                customer_id: cust_UkLWZg9DAJ
                freight_summary:
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/StoreCreditApplyParams"
        required: true
    delete:
      summary: Remove store credit from an order
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Removes any applied store credit from the order.

        **Required scope:** `write_store_credits` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.orders.storeCredits.remove('or_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /orders/{order_id}/store_credits
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      responses:
        '204':
          description: store credit removed
  "/api/v3/admin/orders":
    get:
      summary: List orders
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a paginated list of orders for the current store.

        **Required scope:** `read_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: orders, meta } = await client.orders.list({
            status_eq: 'complete',
            completed_at_gt: '2026-01-01',
            sort: '-completed_at',
            limit: 25,
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /orders -d '{"status_eq":"complete","completed_at_gt":"2026-01-01","sort":"-completed_at","limit":25}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches order number or purchase order number (partial), the
          billing first or last name, or the exact email.
      - name: q[complete]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `complete`.
      - name: q[incomplete]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `incomplete`.
      - name: q[partially_refunded]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `partially_refunded`.
      - name: q[refunded]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `refunded`.
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: sort
        in: query
        required: false
        description: Sort field (e.g., created_at, -created_at, completed_at)
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., items, fulfillments,
          payments, customer, discounts, billing_address, shipping_address). Use dot
          notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., number,total,status,completed_at).
          id is always included.
        schema:
          type: string
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `channel_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `completed_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `considered_risky` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
          | `coupon_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `currency` | One of the `CurrencyCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `customer_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `delivery_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `fulfillment_status` | One of `backorder`, `canceled`, `partial`, `unfulfilled`, `fulfilled`, `delivered`, `pending`, `ready`, `shipped` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `item_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `locale` | One of the `LocaleCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `market_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `order_group_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `payment_status` | One of `none`, `authorized`, `partially_paid`, `paid`, `partially_refunded`, `refunded`, `overcharged`, `voided`, `balance_due`, `credit_owed`, `failed`, `void` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `po_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `status` | One of `draft`, `placed`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `total_quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[bill_address_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
          | `customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
          | `customer_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `customer_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `customer_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |
          | `customer_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `customer_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |
          | `customer_tags_` | `created_at`, `id`, `name`, `updated_at` |
          | `fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
          | `line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
          | `line_items_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
          | `line_items_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |
          | `order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
          | `order_group_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
          | `promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
          | `promotions_coupon_codes_` | `code`, `created_at`, `id`, `promotion_id`, `state`, `updated_at` |
          | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `shipments_` | `created_at`, `id`, `number`, `updated_at` |
          | `store_` | `created_at`, `id`, `name`, `updated_at` |
          | `tags_` | `created_at`, `id`, `name`, `updated_at` |

          </Accordion>

          **Sort by:** `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Order
        sortable:
        - channel_id
        - completed_at
        - considered_risky
        - coupon_code
        - created_at
        - currency
        - customer_id
        - delivery_total
        - email
        - fulfillment_status
        - id
        - item_total
        - locale
        - market_id
        - number
        - order_group_id
        - payment_state
        - payment_status
        - po_number
        - seller_id
        - shipment_state
        - status
        - total
        - total_quantity
        - updated_at
      responses:
        '200':
          description: orders found
          content:
            application/json:
              example:
                data:
                - id: or_UkLWZg9DAJ
                  market_id: mkt_UkLWZg9DAJ
                  withdrawal_period_ends_at:
                  within_withdrawal_period: false
                  shipping_eq_billing_address: false
                  cart_id:
                  channel_id: ch_UkLWZg9DAJ
                  company_id:
                  company_name:
                  po_document_filename:
                  po_document_byte_size:
                  number: R1001
                  email: [email protected]
                  customer_note:
                  po_number:
                  currency: USD
                  locale: en
                  total_quantity: 0
                  coupon_code:
                  fulfillment_status:
                  payment_status:
                  completed_at:
                  item_total: '0.00'
                  discount_total: '0.00'
                  tax_total: '0.00'
                  included_tax_total: '0.00'
                  additional_tax_total: '0.00'
                  delivery_total: '0.00'
                  fee_total:
                  gift_card_total: '0.00'
                  store_credit_total: '0.00'
                  total: '0.00'
                  amount_due: '0.00'
                  covered_by_store_credit: false
                  adjustment_total: '0.00'
                  gift_card:
                  market:
                    id: mkt_UkLWZg9DAJ
                    name: United States
                    currency: USD
                    default_locale: en
                    tax_inclusive: false
                    default: true
                    country_codes:
                    - US
                    supported_locales:
                    - en
                    created_at: '2026-01-15T12:00:00.000Z'
                    updated_at: '2026-01-15T12:00:00.000Z'
                    tax_provider:
                  external_references: {}
                  status: draft
                  last_ip_address:
                  considered_risky: false
                  confirmation_delivered: false
                  store_owner_notification_delivered:
                  metadata: {}
                  cancel_note:
                  canceled_at:
                  approved_at:
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  payment_total: '0.00'
                  commission_amount_total: '0.00'
                  commission_tax_total: '0.00'
                  commission_total: '0.00'
                  preferred_stock_location_id:
                  po_document_url:
                  seller_id:
                  order_group_id:
                  tags: []
                  internal_note:
                  internal_note_html:
                  approver_id:
                  approver_type:
                  canceler_id:
                  canceler_type:
                  created_by_id:
                  created_by_type:
                  cancel_reason_id:
                  cancel_reason_name:
                  customer_id: cust_UkLWZg9DAJ
                  freight_summary:
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  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 draft order
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // One-shot order create: customer, items, addresses, market, channel,
          // notes, metadata, and a coupon code in a single call. Everything
          // except `email` is optional.
          const order = await client.orders.create({
            email: '[email protected]',
            customer_id: 'cus_UkLWZg9DAJ', // Existing customer; omit for guest orders
            use_customer_default_address: false, // true to copy the customer's saved addresses

            currency: 'USD',
            market_id: 'mkt_UkLWZg9DAJ',
            channel_id: 'ch_UkLWZg9DAJ', // Optional — defaults to the store's primary channel
            locale: 'en-US',

            // Pin the order's preferred fulfillment location. Order Routing's
            // built-in PreferredLocation rule ranks this location first when
            // it stocks the cart's items; if it doesn't, routing falls back
            // to the next rule (Minimize Splits → Default Location).
            preferred_stock_location_id: 'sloc_UkLWZg9DAJ',

            customer_note: 'Please leave at the front desk.',
            // Rich text: send HTML. Reads return this as plain text, plus
            // `internal_note_html` with the markup.
            internal_note: '<p>VIP customer — handle with care.</p>',
            metadata: {
              external_reference: 'subscription_invoice_2026_04',
              source: 'recurring-engine',
            },

            // Items: each variant_id + quantity. Optional metadata per line.
            items: [
              { variant_id: 'variant_k5nR8xLq', quantity: 2 },
              { variant_id: 'variant_QXyZ12abCD', quantity: 1, metadata: { gift: true } },
            ],

            // Provide addresses inline OR by ID (existing customer addresses).
            shipping_address: {
              first_name: 'Jane',
              last_name: 'Doe',
              address1: '350 Fifth Avenue',
              address2: 'Floor 42',
              city: 'New York',
              postal_code: '10118',
              country_code: 'US',
              state_code: 'NY',
              phone: '+1 212 555 1234',
              company: 'Acme Inc.',
            },
            // shipping_address_id: 'addr_UkLWZg9DAJ',  // alternative to inline

            billing_address: {
              first_name: 'Jane',
              last_name: 'Doe',
              address1: '350 Fifth Avenue',
              city: 'New York',
              postal_code: '10118',
              country_code: 'US',
              state_code: 'NY',
              phone: '+1 212 555 1234',
            },
            // billing_address_id: 'addr_UkLWZg9DAJ',

            // Optional. Invalid codes are non-fatal — the order is created either way.
            coupon_code: 'WELCOME10',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /orders -d '{"email":"[email protected]","customer_id":"cus_UkLWZg9DAJ","use_customer_default_address":false,"currency":"USD","market_id":"mkt_UkLWZg9DAJ","channel_id":"ch_UkLWZg9DAJ","locale":"en-US","preferred_stock_location_id":"sloc_UkLWZg9DAJ","customer_note":"Please
          leave at the front desk.","internal_note":"<p>VIP customer — handle with
          care.</p>","metadata":{"external_reference":"subscription_invoice_2026_04","source":"recurring-engine"},"items":[{"variant_id":"variant_k5nR8xLq","quantity":2},{"variant_id":"variant_QXyZ12abCD","quantity":1,"metadata":{"gift":true}}],"shipping_address":{"first_name":"Jane","last_name":"Doe","address1":"350
          Fifth Avenue","address2":"Floor 42","city":"New York","postal_code":"10118","country_code":"US","state_code":"NY","phone":"+1
          212 555 1234","company":"Acme Inc."},"billing_address":{"first_name":"Jane","last_name":"Doe","address1":"350
          Fifth Avenue","city":"New York","postal_code":"10118","country_code":"US","state_code":"NY","phone":"+1
          212 555 1234"},"coupon_code":"WELCOME10"}'
      description: |-
        Creates a new draft order in one shot. Customer, items, addresses, currency,
        market, channel, locale, notes, metadata, and a coupon code can all be
        provided inline.

        Setting `preferred_stock_location_id` pins the order's preferred fulfillment
        location — Order Routing's built-in `PreferredLocation` rule consumes it
        when picking which stock location ships each shipment.

        Invalid coupon codes are non-fatal — the order is created and the failure
        is reported on the service result (not in the API response body for now).


        **Required scope:** `write_orders` (for API-key authentication).
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '201':
          description: order created with preferred_stock_location_id
          content:
            application/json:
              example:
                id: or_gbHJdmfrXB
                market_id: mkt_UkLWZg9DAJ
                withdrawal_period_ends_at:
                within_withdrawal_period: false
                shipping_eq_billing_address: false
                cart_id:
                channel_id: ch_UkLWZg9DAJ
                company_id:
                company_name:
                po_document_filename:
                po_document_byte_size:
                number: R1002
                email: [email protected]
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 0
                coupon_code:
                fulfillment_status:
                payment_status:
                completed_at:
                item_total: '0.00'
                discount_total: '0.00'
                tax_total: '0.00'
                included_tax_total: '0.00'
                additional_tax_total: '0.00'
                delivery_total: '0.00'
                fee_total: '0.00'
                gift_card_total: '0.00'
                store_credit_total: '0.00'
                total: '0.00'
                amount_due: '0.00'
                covered_by_store_credit: false
                adjustment_total: '0.00'
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  tax_provider:
                external_references: {}
                status: draft
                last_ip_address:
                considered_risky: false
                confirmation_delivered: false
                store_owner_notification_delivered:
                metadata: {}
                cancel_note:
                canceled_at:
                approved_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                payment_total: '0.00'
                commission_amount_total: '0.00'
                commission_tax_total: '0.00'
                commission_total: '0.00'
                preferred_stock_location_id: sloc_UkLWZg9DAJ
                po_document_url:
                seller_id:
                order_group_id:
                tags: []
                internal_note:
                internal_note_html:
                approver_id:
                approver_type:
                canceler_id:
                canceler_type:
                created_by_id: adm_UkLWZg9DAJ
                created_by_type: admin_user
                cancel_reason_id:
                cancel_reason_name:
                customer_id:
                freight_summary:
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/OrderCreateParams"
        required: true
  "/api/v3/admin/orders/{id}":
    get:
      summary: Show an order
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns full order details including admin-only fields.

        **Required scope:** `read_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const order = await client.orders.get('or_UkLWZg9DAJ', {
            expand: ['items', 'fulfillments', 'payments', 'customer'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /orders/{id} -d '{"expand":["items","fulfillments","payments","customer"]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Order ID (e.g., or_xxx)
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., items, fulfillments,
          payments, customer, discounts, billing_address, shipping_address). Use dot
          notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., number,total,status,completed_at).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: order found
          content:
            application/json:
              example:
                id: or_UkLWZg9DAJ
                market_id: mkt_UkLWZg9DAJ
                withdrawal_period_ends_at:
                within_withdrawal_period: false
                shipping_eq_billing_address: false
                cart_id:
                channel_id: ch_UkLWZg9DAJ
                company_id:
                company_name:
                po_document_filename:
                po_document_byte_size:
                number: R1001
                email: [email protected]
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 0
                coupon_code:
                fulfillment_status:
                payment_status:
                completed_at:
                item_total: '0.00'
                discount_total: '0.00'
                tax_total: '0.00'
                included_tax_total: '0.00'
                additional_tax_total: '0.00'
                delivery_total: '0.00'
                fee_total:
                gift_card_total: '0.00'
                store_credit_total: '0.00'
                total: '0.00'
                amount_due: '0.00'
                covered_by_store_credit: false
                adjustment_total: '0.00'
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  tax_provider:
                external_references: {}
                status: draft
                last_ip_address:
                considered_risky: false
                confirmation_delivered: false
                store_owner_notification_delivered:
                metadata: {}
                cancel_note:
                canceled_at:
                approved_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                payment_total: '0.00'
                commission_amount_total: '0.00'
                commission_tax_total: '0.00'
                commission_total: '0.00'
                preferred_stock_location_id:
                po_document_url:
                seller_id:
                order_group_id:
                tags: []
                internal_note:
                internal_note_html:
                approver_id:
                approver_type:
                canceler_id:
                canceler_type:
                created_by_id:
                created_by_type:
                cancel_reason_id:
                cancel_reason_name:
                customer_id: cust_UkLWZg9DAJ
                freight_summary:
        '404':
          description: order not found
          content:
            application/json:
              example:
                error:
                  code: order_not_found
                  message: Order not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update an order
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Updates an order. Supports updating email, addresses, special instructions, and line items.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const order = await client.orders.update('or_UkLWZg9DAJ', {
            email: '[email protected]',
            internal_note: '<p>VIP — gift wrap on next order</p>',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{id} -d '{"email":"[email protected]","internal_note":"<p>VIP
          — gift wrap on next order</p>"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      responses:
        '200':
          description: order updated
          content:
            application/json:
              example:
                id: or_UkLWZg9DAJ
                market_id: mkt_UkLWZg9DAJ
                withdrawal_period_ends_at:
                within_withdrawal_period: false
                shipping_eq_billing_address: false
                cart_id:
                channel_id: ch_UkLWZg9DAJ
                company_id:
                company_name:
                po_document_filename:
                po_document_byte_size:
                number: R1001
                email: [email protected]
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 0
                coupon_code:
                fulfillment_status:
                payment_status: none
                completed_at:
                item_total: '0.00'
                discount_total: '0.00'
                tax_total: '0.00'
                included_tax_total: '0.00'
                additional_tax_total: '0.00'
                delivery_total: '0.00'
                fee_total: '0.00'
                gift_card_total: '0.00'
                store_credit_total: '0.00'
                total: '0.00'
                amount_due: '0.00'
                covered_by_store_credit: false
                adjustment_total: '0.00'
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  tax_provider:
                external_references: {}
                status: draft
                last_ip_address:
                considered_risky: false
                confirmation_delivered: false
                store_owner_notification_delivered:
                metadata: {}
                cancel_note:
                canceled_at:
                approved_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                payment_total: '0.00'
                commission_amount_total: '0.00'
                commission_tax_total: '0.00'
                commission_total: '0.00'
                preferred_stock_location_id:
                po_document_url:
                seller_id:
                order_group_id:
                tags: []
                internal_note:
                internal_note_html:
                approver_id:
                approver_type:
                canceler_id:
                canceler_type:
                created_by_id:
                created_by_type:
                cancel_reason_id:
                cancel_reason_name:
                customer_id: cust_UkLWZg9DAJ
                freight_summary:
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/OrderUpdateParams"
        required: true
    delete:
      summary: Delete a draft order
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Deletes a draft order. Completed orders cannot be deleted.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.orders.delete('or_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /orders/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      responses:
        '204':
          description: order deleted
  "/api/v3/admin/orders/{id}/complete":
    patch:
      summary: Complete an order
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Completes an order in the `confirm` state, marking it as placed.

        Set `notify_customer: true` to send the order confirmation email.

        On a marketplace, an order holding several sellers' goods becomes one
        order per seller, and the response is the order group they belong to
        with those orders nested inside it.


        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const result = await client.orders.complete('or_UkLWZg9DAJ', {
            notify_customer: true,
          })

          // An order holding several sellers' goods becomes one order per seller.
          const orders = isOrderGroup(result) ? result.orders : [result]
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{id}/complete -d '{"notify_customer":true}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      responses:
        '200':
          description: order completed
          content:
            application/json:
              example:
                id: or_UkLWZg9DAJ
                market_id: mkt_UkLWZg9DAJ
                withdrawal_period_ends_at:
                within_withdrawal_period: true
                shipping_eq_billing_address: false
                cart_id:
                channel_id: ch_UkLWZg9DAJ
                company_id:
                company_name:
                po_document_filename:
                po_document_byte_size:
                number: R1001
                email: [email protected]
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                coupon_code:
                fulfillment_status: unfulfilled
                payment_status: paid
                completed_at: '2026-01-15T12:00:00.000Z'
                item_total: '10.00'
                discount_total: '0.00'
                tax_total: '0.00'
                included_tax_total: '0.00'
                additional_tax_total: '0.00'
                delivery_total: '100.00'
                fee_total: '0.00'
                gift_card_total: '0.00'
                store_credit_total: '0.00'
                total: '110.00'
                amount_due: '0.00'
                covered_by_store_credit: false
                adjustment_total: '0.00'
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  tax_provider:
                external_references: {}
                status: placed
                last_ip_address:
                considered_risky: false
                confirmation_delivered: false
                store_owner_notification_delivered:
                metadata: {}
                cancel_note:
                canceled_at:
                approved_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                payment_total: '110.00'
                commission_amount_total: '0.00'
                commission_tax_total: '0.00'
                commission_total: '0.00'
                preferred_stock_location_id:
                po_document_url:
                seller_id:
                order_group_id:
                tags: []
                internal_note:
                internal_note_html:
                approver_id:
                approver_type:
                canceler_id:
                canceler_type:
                created_by_id:
                created_by_type:
                cancel_reason_id:
                cancel_reason_name:
                customer_id: cust_UkLWZg9DAJ
                freight_summary:
        '422':
          description: order cannot be completed
          content:
            application/json:
              example:
                error:
                  code: order_cannot_complete
                  message: No payment found
                  details:
                    base:
                    - code:
                      message: No payment found
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/OrderCompleteParams"
        required: true
  "/api/v3/admin/orders/{id}/cancel":
    patch:
      summary: Cancel an order
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Cancels a completed order.

        `cancel_reason_id` records why, from the store's own cancellation-reason
        vocabulary (`/admin/order_cancellation_reasons`), and `cancel_note` is a
        staff-facing note; both are shown on the order afterwards.

        Stock is always released — the goods are not going out either way — and
        every payment is settled at the gateway, which releases an
        authorization it never drew on and refunds a charge it cannot release.

        `refund_payments` and `refund_amount` govern the shared payment of a
        split checkout, where one payment covers several orders: they decide
        whether this order's share comes back, and how much of it. A
        `refund_amount` on an ordinary order is refused with a 422.

        Set `notify_customer: true` to send the order cancellation email.


        **Required scope:** `write_orders`, plus `write_refunds` with `refund_payments` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // A split checkout: the payment is shared, so what comes back is this order's
          // own share. refund_amount names part of that share, keeping the rest back.
          const order = await client.orders.cancel('or_UkLWZg9DAJ', {
            cancel_reason_id: 'ocr_UkLWZg9DAJ',
            cancel_note: 'Supplier could not deliver in time',
            refund_payments: true,
            refund_amount: '25.00',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{id}/cancel -d '{"cancel_reason_id":"ocr_UkLWZg9DAJ","cancel_note":"Supplier
          could not deliver in time","refund_payments":true,"refund_amount":"25.00"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      responses:
        '200':
          description: order canceled
          content:
            application/json:
              example:
                id: or_UkLWZg9DAJ
                market_id: mkt_UkLWZg9DAJ
                withdrawal_period_ends_at:
                within_withdrawal_period: false
                shipping_eq_billing_address: false
                cart_id:
                channel_id: ch_UkLWZg9DAJ
                company_id:
                company_name:
                po_document_filename:
                po_document_byte_size:
                number: R1001
                email: [email protected]
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                coupon_code:
                fulfillment_status: canceled
                payment_status: none
                completed_at: '2026-01-15T12:00:00.000Z'
                item_total: '10.00'
                discount_total: '0.00'
                tax_total: '0.00'
                included_tax_total: '0.00'
                additional_tax_total: '0.00'
                delivery_total: '100.00'
                fee_total: '0.00'
                gift_card_total: '0.00'
                store_credit_total: '0.00'
                total: '110.00'
                amount_due: '0.00'
                covered_by_store_credit: false
                adjustment_total: '0.00'
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  tax_provider:
                external_references: {}
                status: canceled
                last_ip_address:
                considered_risky: false
                confirmation_delivered: false
                store_owner_notification_delivered:
                metadata: {}
                cancel_note:
                canceled_at: '2026-01-15T12:00:00.000Z'
                approved_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                payment_total: '0.00'
                commission_amount_total: '0.00'
                commission_tax_total: '0.00'
                commission_total: '0.00'
                preferred_stock_location_id:
                po_document_url:
                seller_id:
                order_group_id:
                tags: []
                internal_note:
                internal_note_html:
                approver_id:
                approver_type:
                canceler_id: adm_UkLWZg9DAJ
                canceler_type: admin_user
                created_by_id:
                created_by_type:
                cancel_reason_id:
                cancel_reason_name:
                customer_id: cust_UkLWZg9DAJ
                freight_summary:
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/OrderCancelParams"
        required: true
  "/api/v3/admin/orders/{id}/approve":
    patch:
      summary: Approve an order
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Approves an order (e.g., for fraud review).

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const order = await client.orders.approve('or_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{id}/approve -d '{ ... }'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      responses:
        '200':
          description: order approved
          content:
            application/json:
              example:
                id: or_UkLWZg9DAJ
                market_id: mkt_UkLWZg9DAJ
                withdrawal_period_ends_at:
                within_withdrawal_period: true
                shipping_eq_billing_address: false
                cart_id:
                channel_id: ch_UkLWZg9DAJ
                company_id:
                company_name:
                po_document_filename:
                po_document_byte_size:
                number: R1001
                email: [email protected]
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                coupon_code:
                fulfillment_status:
                payment_status:
                completed_at: '2026-01-15T12:00:00.000Z'
                item_total: '10.00'
                discount_total: '0.00'
                tax_total: '0.00'
                included_tax_total: '0.00'
                additional_tax_total: '0.00'
                delivery_total: '100.00'
                fee_total: '0.00'
                gift_card_total: '0.00'
                store_credit_total: '0.00'
                total: '110.00'
                amount_due: '110.00'
                covered_by_store_credit: false
                adjustment_total: '0.00'
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  tax_provider:
                external_references: {}
                status: placed
                last_ip_address:
                considered_risky: false
                confirmation_delivered: false
                store_owner_notification_delivered:
                metadata: {}
                cancel_note:
                canceled_at:
                approved_at: '2026-01-15T12:00:00.000Z'
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                payment_total: '0.00'
                commission_amount_total: '0.00'
                commission_tax_total: '0.00'
                commission_total: '0.00'
                preferred_stock_location_id:
                po_document_url:
                seller_id:
                order_group_id:
                tags: []
                internal_note:
                internal_note_html:
                approver_id: adm_UkLWZg9DAJ
                approver_type: admin_user
                canceler_id:
                canceler_type:
                created_by_id:
                created_by_type:
                cancel_reason_id:
                cancel_reason_name:
                customer_id: cust_UkLWZg9DAJ
                freight_summary:
  "/api/v3/admin/orders/{id}/resend_confirmation":
    post:
      summary: Resend confirmation email
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Publishes the order.completed event to trigger confirmation email delivery.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.orders.resendConfirmation('or_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api post /orders/{id}/resend_confirmation -d '{ ... }'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      responses:
        '200':
          description: confirmation resent
          content:
            application/json:
              example:
                id: or_UkLWZg9DAJ
                market_id: mkt_UkLWZg9DAJ
                withdrawal_period_ends_at:
                within_withdrawal_period: true
                shipping_eq_billing_address: false
                cart_id:
                channel_id: ch_UkLWZg9DAJ
                company_id:
                company_name:
                po_document_filename:
                po_document_byte_size:
                number: R1001
                email: [email protected]
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                coupon_code:
                fulfillment_status:
                payment_status:
                completed_at: '2026-01-15T12:00:00.000Z'
                item_total: '10.00'
                discount_total: '0.00'
                tax_total: '0.00'
                included_tax_total: '0.00'
                additional_tax_total: '0.00'
                delivery_total: '100.00'
                fee_total: '0.00'
                gift_card_total: '0.00'
                store_credit_total: '0.00'
                total: '110.00'
                amount_due: '110.00'
                covered_by_store_credit: false
                adjustment_total: '0.00'
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  tax_provider:
                external_references: {}
                status: placed
                last_ip_address:
                considered_risky: false
                confirmation_delivered: false
                store_owner_notification_delivered:
                metadata: {}
                cancel_note:
                canceled_at:
                approved_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                payment_total: '0.00'
                commission_amount_total: '0.00'
                commission_tax_total: '0.00'
                commission_total: '0.00'
                preferred_stock_location_id:
                po_document_url:
                seller_id:
                order_group_id:
                tags: []
                internal_note:
                internal_note_html:
                approver_id:
                approver_type:
                canceler_id:
                canceler_type:
                created_by_id:
                created_by_type:
                cancel_reason_id:
                cancel_reason_name:
                customer_id: cust_UkLWZg9DAJ
                freight_summary:
  "/api/v3/admin/orders/{id}/resend_digital_links":
    post:
      summary: Resend digital download links
      tags:
      - Orders
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.orders.resendDigitalLinks('or_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api post /orders/{id}/resend_digital_links -d '{ ... }'
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Emails the customer their download links for the digital products on
        this order again. Nothing is sent when the order has no digital links or
        the store does not send transactional emails. Use it when the original
        email was lost; to restore used-up downloads or an expired link, reset
        the digital link instead.


        **Required scope:** `write_orders` (for API-key authentication).
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      responses:
        '200':
          description: digital links resent
          content:
            application/json:
              example:
                id: or_UkLWZg9DAJ
                market_id: mkt_UkLWZg9DAJ
                withdrawal_period_ends_at:
                within_withdrawal_period: true
                shipping_eq_billing_address: false
                cart_id:
                channel_id: ch_UkLWZg9DAJ
                company_id:
                company_name:
                po_document_filename:
                po_document_byte_size:
                number: R1001
                email: [email protected]
                customer_note:
                po_number:
                currency: USD
                locale: en
                total_quantity: 1
                coupon_code:
                fulfillment_status:
                payment_status:
                completed_at: '2026-01-15T12:00:00.000Z'
                item_total: '10.00'
                discount_total: '0.00'
                tax_total: '0.00'
                included_tax_total: '0.00'
                additional_tax_total: '0.00'
                delivery_total: '100.00'
                fee_total: '0.00'
                gift_card_total: '0.00'
                store_credit_total: '0.00'
                total: '110.00'
                amount_due: '110.00'
                covered_by_store_credit: false
                adjustment_total: '0.00'
                gift_card:
                market:
                  id: mkt_UkLWZg9DAJ
                  name: United States
                  currency: USD
                  default_locale: en
                  tax_inclusive: false
                  default: true
                  country_codes:
                  - US
                  supported_locales:
                  - en
                  created_at: '2026-11-03T16:44:09.130Z'
                  updated_at: '2026-11-03T16:44:09.130Z'
                  tax_provider:
                external_references: {}
                status: placed
                last_ip_address:
                considered_risky: false
                confirmation_delivered: false
                store_owner_notification_delivered:
                metadata: {}
                cancel_note:
                canceled_at:
                approved_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                payment_total: '0.00'
                commission_amount_total: '0.00'
                commission_tax_total: '0.00'
                commission_total: '0.00'
                preferred_stock_location_id:
                po_document_url:
                seller_id:
                order_group_id:
                tags: []
                internal_note:
                internal_note_html:
                approver_id:
                approver_type:
                canceler_id:
                canceler_type:
                created_by_id:
                created_by_type:
                cancel_reason_id:
                cancel_reason_name:
                customer_id: cust_UkLWZg9DAJ
                freight_summary:
              schema:
                "$ref": "#/components/schemas/Order"
  "/api/v3/admin/returns":
    get:
      summary: List returns
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Every return in the store, across all orders.

        **Required scope:** `read_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: returns } = await client.returns.list({
            status_eq: 'requested',
            sort: '-created_at',
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /returns -d '{"status_eq":"requested","sort":"-created_at"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of number (partial, case-insensitive).
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `status` | One of `requested`, `approved`, `received`, `refunded`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
          | `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
          | `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
          | `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
          | `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
          | `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
          | `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
          | `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
          | `order_store_` | `created_at`, `id`, `name`, `updated_at` |
          | `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
          | `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |

          </Accordion>

          **Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Return
        sortable:
        - created_at
        - id
        - number
        - status
        - updated_at
      responses:
        '200':
          description: returns listed
          content:
            application/json:
              example:
                data:
                - id: ret_UkLWZg9DAJ
                  number: RET1001
                  status: requested
                  order_id: or_UkLWZg9DAJ
                  reason_id:
                  refund_total: '10.00'
                  refund_tax_total: '0.00'
                  approved_at:
                  received_at:
                  refunded_at:
                  canceled_at:
                  external_references: {}
                  memo: Item did not fit
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  stock_location_id: sloc_UkLWZg9DAJ
                  created_by_id:
                  created_by_type:
                  refunded_total: '0.00'
                  refundable_total: '10.00'
                  documents: []
                  labels: []
                  deliveries: []
                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/Return"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
  "/api/v3/admin/orders/{order_id}/returns":
    get:
      summary: List order returns
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        The returns opened on one order.

        **Required scope:** `read_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: returns } = await client.orders.returns.list('or_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /orders/{order_id}/returns
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of number (partial, case-insensitive).
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `status` | One of `requested`, `approved`, `received`, `refunded`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
          | `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
          | `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
          | `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
          | `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
          | `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
          | `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
          | `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
          | `order_store_` | `created_at`, `id`, `name`, `updated_at` |
          | `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
          | `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |

          </Accordion>

          **Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Return
        sortable:
        - created_at
        - id
        - number
        - status
        - updated_at
      responses:
        '200':
          description: returns listed
          content:
            application/json:
              example:
                data:
                - id: ret_UkLWZg9DAJ
                  number: RET1001
                  status: requested
                  order_id: or_UkLWZg9DAJ
                  reason_id:
                  refund_total: '10.00'
                  refund_tax_total: '0.00'
                  approved_at:
                  received_at:
                  refunded_at:
                  canceled_at:
                  external_references: {}
                  memo: Item did not fit
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  stock_location_id: sloc_UkLWZg9DAJ
                  created_by_id:
                  created_by_type:
                  refunded_total: '0.00'
                  refundable_total: '10.00'
                  documents: []
                  labels: []
                  deliveries: []
                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/Return"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
    post:
      summary: Create a return
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Opens a return on a completed order for fulfilled units the customer is sending back.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const orderReturn = await client.orders.returns.create('or_UkLWZg9DAJ', {
            reason_id: 'rar_UkLWZg9DAJ',
            items: [{ fulfillment_item_id: 'fi_UkLWZg9DAJ', quantity: 1 }],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /orders/{order_id}/returns -d '{"reason_id":"rar_UkLWZg9DAJ","items":[{"fulfillment_item_id":"fi_UkLWZg9DAJ","quantity":1}]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      responses:
        '201':
          description: return opened
          content:
            application/json:
              example:
                id: ret_gbHJdmfrXB
                number: RET1002
                status: requested
                order_id: or_gbHJdmfrXB
                reason_id:
                refund_total: '10.00'
                refund_tax_total: '0.00'
                approved_at:
                received_at:
                refunded_at:
                canceled_at:
                external_references: {}
                memo: Too small
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                stock_location_id: sloc_UkLWZg9DAJ
                created_by_id: adm_UkLWZg9DAJ
                created_by_type: admin_user
                refunded_total: '0.00'
                refundable_total: '10.00'
                documents: []
                labels: []
                deliveries: []
              schema:
                "$ref": "#/components/schemas/Return"
        '422':
          description: more returned than was fulfilled
          content:
            application/json:
              example:
                error:
                  code: processing_error
                  message: Only 1 of Product 1792493 can be returned
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReturnCreateParams"
        required: true
  "/api/v3/admin/orders/{order_id}/returns/{id}":
    patch:
      summary: Update a return
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Edits the warehouse, reason, memo or metadata of a return. Its status moves only through the approve, receive, refund and cancel actions.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const orderReturn = await client.orders.returns.update('or_UkLWZg9DAJ', 'ret_UkLWZg9DAJ', {
            stock_location_id: 'sloc_UkLWZg9DAJ',
            memo: 'Send to the returns warehouse',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/returns/{id} -d '{"stock_location_id":"sloc_UkLWZg9DAJ","memo":"Send
          to the returns warehouse"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Return prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: return updated
          content:
            application/json:
              example:
                id: ret_UkLWZg9DAJ
                number: RET1001
                status: requested
                order_id: or_UkLWZg9DAJ
                reason_id: rar_UkLWZg9DAJ
                refund_total: '10.00'
                refund_tax_total: '0.00'
                approved_at:
                received_at:
                refunded_at:
                canceled_at:
                external_references: {}
                memo: Customer shipped it back with a tracking number
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                stock_location_id: sloc_UkLWZg9DAJ
                created_by_id:
                created_by_type:
                refunded_total: '0.00'
                refundable_total: '10.00'
                documents: []
                labels: []
                deliveries: []
              schema:
                "$ref": "#/components/schemas/Return"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReturnUpdateParams"
        required: true
  "/api/v3/admin/orders/{order_id}/returns/{id}/approve":
    patch:
      summary: Approve a return
      tags:
      - Orders
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const orderReturn = await client.orders.returns.approve('or_UkLWZg9DAJ', 'ret_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/returns/{id}/approve -d '{ ...
          }'
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Accepts a requested return so the customer can send the goods back. Only a requested return can be approved; receive it once the goods arrive.

        **Required scope:** `write_orders` (for API-key authentication).
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Return prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: return approved
          content:
            application/json:
              example:
                id: ret_UkLWZg9DAJ
                number: RET1001
                status: approved
                order_id: or_UkLWZg9DAJ
                reason_id:
                refund_total: '10.00'
                refund_tax_total: '0.00'
                approved_at: '2026-01-15T12:00:00Z'
                received_at:
                refunded_at:
                canceled_at:
                external_references: {}
                memo: Item did not fit
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                stock_location_id: sloc_UkLWZg9DAJ
                created_by_id: adm_UkLWZg9DAJ
                created_by_type: admin_user
                refunded_total: '0.00'
                refundable_total: '10.00'
                documents: []
                labels: []
                deliveries: []
              schema:
                "$ref": "#/components/schemas/Return"
        '422':
          description: the return is not requested
          content:
            application/json:
              example:
                error:
                  code: processing_error
                  message: Not requested
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/admin/orders/{order_id}/returns/{id}/receive":
    patch:
      summary: Receive a return
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Records what arrived on an approved return. Omit `items` to receive everything as requested and resellable; send rows for a partial or damaged receipt.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Omit `items` to receive everything as requested and resellable.
          const orderReturn = await client.orders.returns.receive('or_UkLWZg9DAJ', 'ret_UkLWZg9DAJ', {
            items: [{ return_line_item_id: 'rli_UkLWZg9DAJ', quantity: 1, resellable: false }],
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/returns/{id}/receive -d '{"items":[{"return_line_item_id":"rli_UkLWZg9DAJ","quantity":1,"resellable":false}]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Return prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: return received
          content:
            application/json:
              example:
                id: ret_UkLWZg9DAJ
                number: RET1001
                status: received
                order_id: or_UkLWZg9DAJ
                reason_id:
                refund_total: '10.00'
                refund_tax_total: '0.00'
                approved_at: '2026-01-15T12:00:00Z'
                received_at: '2026-01-15T12:00:00Z'
                refunded_at:
                canceled_at:
                external_references: {}
                memo: Item did not fit
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                stock_location_id: sloc_UkLWZg9DAJ
                created_by_id:
                created_by_type:
                refunded_total: '0.00'
                refundable_total: '10.00'
                documents: []
                labels: []
                deliveries: []
              schema:
                "$ref": "#/components/schemas/Return"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReturnReceiveParams"
  "/api/v3/admin/orders/{order_id}/returns/{id}/refund":
    patch:
      summary: Refund a return
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Pays the customer back for a received return, to store credit or through the original payment.

        **Required scope:** `write_orders` and `write_refunds` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const orderReturn = await client.orders.returns.refund('or_UkLWZg9DAJ', 'ret_UkLWZg9DAJ', {
            amount: '29.99',
            refund_method: 'original_payment',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/returns/{id}/refund -d '{"amount":"29.99","refund_method":"original_payment"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Return prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: return refunded
          content:
            application/json:
              example:
                id: ret_UkLWZg9DAJ
                number: RET1001
                status: refunded
                order_id: or_UkLWZg9DAJ
                reason_id:
                refund_total: '10.00'
                refund_tax_total: '0.00'
                approved_at: '2026-01-14T12:00:00Z'
                received_at: '2026-01-15T12:00:00Z'
                refunded_at: '2026-01-15T12:00:00Z'
                canceled_at:
                external_references: {}
                memo: Item did not fit
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                stock_location_id: sloc_UkLWZg9DAJ
                created_by_id:
                created_by_type:
                refunded_total: '10.00'
                refundable_total: '0.00'
                documents: []
                labels: []
                deliveries: []
              schema:
                "$ref": "#/components/schemas/Return"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReturnRefundParams"
  "/api/v3/admin/orders/{order_id}/returns/{id}/cancel":
    patch:
      summary: Cancel a return
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Withdraws a return whose goods have not been received.

        **Required scope:** `write_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const orderReturn = await client.orders.returns.cancel('or_UkLWZg9DAJ', 'ret_UkLWZg9DAJ', {
            reason: 'Customer decided to keep the item',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/returns/{id}/cancel -d '{"reason":"Customer
          decided to keep the item"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Return prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: return canceled
          content:
            application/json:
              example:
                id: ret_UkLWZg9DAJ
                number: RET1001
                status: canceled
                order_id: or_UkLWZg9DAJ
                reason_id:
                refund_total: '10.00'
                refund_tax_total: '0.00'
                approved_at:
                received_at:
                refunded_at:
                canceled_at: '2026-01-15T12:00:00Z'
                external_references: {}
                memo: |-
                  Item did not fit
                  Customer changed their mind
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                stock_location_id: sloc_UkLWZg9DAJ
                created_by_id:
                created_by_type:
                refunded_total: '0.00'
                refundable_total: '10.00'
                documents: []
                labels: []
                deliveries: []
              schema:
                "$ref": "#/components/schemas/Return"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReturnCancelParams"
  "/api/v3/admin/orders/{order_id}/returns/{return_id}/labels":
    get:
      summary: List return labels
      tags:
      - Orders
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        The shipping labels issued for sending one return back to the store.

        **Required scope:** `read_orders` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: labels } = await client.orders.returns.labels.list('or_UkLWZg9DAJ', 'ret_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /orders/{order_id}/returns/{return_id}/labels
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: return_id
        in: path
        required: true
        description: Return prefixed ID
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[carrier_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `carrier` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `source` | One of `purchased`, `uploaded` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `status` | One of `purchased`, `refund_requested`, `refunded` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `tracking_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `carrier`, `created_at`, `id`, `source`, `status`, `tracking_number`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: ShippingLabel
        sortable:
        - carrier
        - created_at
        - id
        - source
        - status
        - tracking_number
        - updated_at
      responses:
        '200':
          description: labels listed
          content:
            application/json:
              example:
                data:
                - id: lbl_UkLWZg9DAJ
                  source: purchased
                  status: purchased
                  carrier: ups
                  carrier_name: UPS
                  service: Ground
                  tracking_number: 1Z879E930346830006
                  currency: USD
                  format: pdf
                  external_id: shp_3
                  metadata: {}
                  refunded_at:
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  owner_id: ret_UkLWZg9DAJ
                  owner_type: return
                  cost: '7.25'
                  integration_id:
                  file_pending: false
                  download_url:
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/ShippingLabel"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
  "/api/v3/admin/orders/{order_id}/returns/{return_id}/labels/{id}/refund":
    patch:
      summary: Refund a return label
      tags:
      - Orders
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const label = await client.orders.returns.labels.refund(
            'or_UkLWZg9DAJ',
            'ret_UkLWZg9DAJ',
            'lbl_UkLWZg9DAJ',
          )
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/returns/{return_id}/labels/{id}/refund
          -d '{ ... }'
      operationId: return_labels_refund
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Asks the carrier to refund a purchased return label the customer never used, such as when the return is canceled. An uploaded label has nothing to refund.

        **Required scope:** `write_orders` (for API-key authentication).
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order prefixed ID
        schema:
          type: string
      - name: return_id
        in: path
        required: true
        description: Return prefixed ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Shipping label prefixed ID
        schema:
          type: string
      responses:
        '200':
          description: refund filed
          content:
            application/json:
              example:
                id: lbl_UkLWZg9DAJ
                source: purchased
                status: refunded
                carrier: ups
                carrier_name: UPS
                service: Ground
                tracking_number: 1Z879E930346830007
                currency: USD
                format: pdf
                external_id: shp_4
                metadata: {}
                refunded_at: '2026-01-15T12:00:00.000Z'
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                owner_id: ret_UkLWZg9DAJ
                owner_type: return
                cost: '7.25'
                integration_id:
                file_pending: false
                download_url:
              schema:
                "$ref": "#/components/schemas/ShippingLabel"
        '422':
          description: uploaded labels cannot be refunded
          content:
            application/json:
              example:
                error:
                  code: processing_error
                  message: An uploaded label was not bought through Spree and cannot
                    be refunded — delete it instead
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/admin/payment_methods/{payment_method_id}/custom_fields":
    get:
      summary: List payment method custom fields
      tags:
      - Payment Methods
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the payment method's custom field values.

        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: customFields } = await client.customFields('payment_method', 'pm_UkLWZg9DAJ').list()
      - lang: bash
        label: Spree CLI
        source: spree api get /payment_methods/{payment_method_id}/custom_fields
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: payment_method_id
        in: path
        required: true
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., custom_field_definition).
          Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., key,value,namespace).
          id is always included.
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: CustomField
        sortable:
        - created_at
        - id
        - updated_at
      responses:
        '200':
          description: custom fields found
          content:
            application/json:
              example:
                data:
                - id: cf_UkLWZg9DAJ
                  label: Title
                  field_type: short_text
                  key: custom.title
                  value: wool
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  storefront_visible: true
                  custom_field_definition_id: cfdef_UkLWZg9DAJ
                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/CustomField"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
  "/api/v3/admin/payment_methods":
    get:
      summary: List payment methods
      tags:
      - Payment Methods
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the store's configured payment methods. Use `source_required: true` to know which methods need a saved source.

        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: paymentMethods } = await client.paymentMethods.list()
      - lang: bash
        label: Spree CLI
        source: spree api get /payment_methods
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of name (partial, case-insensitive).
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand. Use dot notation for
          nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,type,active).
          id is always included.
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `storefront_visible` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
          | `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `active`, `created_at`, `id`, `name`, `position`, `storefront_visible`, `type`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: PaymentMethod
        sortable:
        - active
        - created_at
        - id
        - name
        - position
        - storefront_visible
        - type
        - updated_at
      responses:
        '200':
          description: payment methods found
          content:
            application/json:
              example:
                data:
                - id: pm_UkLWZg9DAJ
                  name: Check 3
                  description:
                  type: check
                  session_required: false
                  source_required: false
                  metadata: {}
                  active: true
                  capture_method:
                  resolved_capture_method: checkout
                  storefront_visible: true
                  position: 1
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  preferences: {}
                  logo_url:
                  docs_url:
                  third_party: false
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
    post:
      summary: Create a payment method
      tags:
      - Payment Methods
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Adds a payment method to the store. `type` is a shorthand from the
        payment method types endpoint, and `preferences` takes the values its
        preference schema declares (gateway credentials among them).


        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const paymentMethod = await client.paymentMethods.create({
            type: 'check',
            name: 'Bank transfer',
            description: 'Pay by bank transfer within 14 days.',
            active: true,
            storefront_visible: true,
            capture_method: 'manual',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /payment_methods -d '{"type":"check","name":"Bank transfer","description":"Pay
          by bank transfer within 14 days.","active":true,"storefront_visible":true,"capture_method":"manual"}'
      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 method created
          content:
            application/json:
              example:
                id: pm_gbHJdmfrXB
                name: Bank transfer
                description: Pay by bank transfer within 14 days.
                type: check
                session_required: false
                source_required: false
                metadata: {}
                active: true
                capture_method: manual
                resolved_capture_method: manual
                storefront_visible: true
                position: 2
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                preferences: {}
                logo_url:
                docs_url:
                third_party: false
        '422':
          description: unknown payment method type
          content:
            application/json:
              example:
                error:
                  code: unknown_payment_method_type
                  message: Unknown type
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PaymentMethodCreateParams"
        required: true
  "/api/v3/admin/payment_methods/types":
    get:
      summary: List available payment provider types
      tags:
      - Payment Methods
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns every registered payment provider with the JSON Schema of its `preferences`. `installed` marks a provider the store already has, which a "Provider" picker leaves out.

        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: types } = await client.paymentMethods.types()
      - lang: bash
        label: Spree CLI
        source: spree api get /payment_methods/types
      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: provider types found
          content:
            application/json:
              example:
                data:
                - type: bogus
                  label: Bogus
                  description:
                  schema:
                    type: object
                    properties:
                      dummy_key:
                        type: string
                        default: PUBLICKEY123
                      dummy_secret_key:
                        type:
                        - string
                        - 'null'
                        x-spree-secret: true
                    additionalProperties: false
                  logo_url:
                  docs_url:
                  third_party: true
                  installed: false
                - type: check
                  label: Check
                  description:
                  schema:
                    type: object
                    properties: {}
                    additionalProperties: false
                  logo_url:
                  docs_url:
                  third_party: false
                  installed: true
                - type: custom_payment_source_method
                  label: Custom Payment Source Method
                  description:
                  schema:
                    type: object
                    properties: {}
                    additionalProperties: false
                  logo_url:
                  docs_url:
                  third_party: false
                  installed: false
                - type: store_credit
                  label: Store Credit
                  description:
                  schema:
                    type: object
                    properties: {}
                    additionalProperties: false
                  logo_url:
                  docs_url:
                  third_party: false
                  installed: true
  "/api/v3/admin/payment_methods/{id}":
    get:
      summary: Show a payment method
      tags:
      - Payment Methods
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a payment method by ID.

        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const paymentMethod = await client.paymentMethods.get('pm_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /payment_methods/{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
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand. Use dot notation for
          nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,type,active).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: payment method found
          content:
            application/json:
              example:
                id: pm_UkLWZg9DAJ
                name: Check 7
                description:
                type: check
                session_required: false
                source_required: false
                metadata: {}
                active: true
                capture_method:
                resolved_capture_method: checkout
                storefront_visible: true
                position: 1
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                preferences: {}
                logo_url:
                docs_url:
                third_party: false
    patch:
      summary: Update a payment method
      tags:
      - Payment Methods
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Updates a payment method. Its `type` is fixed once created.

        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const paymentMethod = await client.paymentMethods.update('pm_UkLWZg9DAJ', {
            name: 'Cheque',
            storefront_visible: false,
            position: 2,
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /payment_methods/{id} -d '{"name":"Cheque","storefront_visible":false,"position":2}'
      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: payment method updated
          content:
            application/json:
              example:
                id: pm_UkLWZg9DAJ
                name: Cheque
                description:
                type: check
                session_required: false
                source_required: false
                metadata: {}
                active: true
                capture_method:
                resolved_capture_method: checkout
                storefront_visible: false
                position: 2
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                preferences: {}
                logo_url:
                docs_url:
                third_party: false
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PaymentMethodUpdateParams"
        required: true
  "/api/v3/admin/orders/{order_id}/payments":
    get:
      summary: List payments
      tags:
      - Payments
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns all payments for an order.

        **Required scope:** `read_payments` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: payments } = await client.orders.payments.list('or_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /orders/{order_id}/payments
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., payment_method,
          source). Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., amount,status,number,response_code).
          id is always included.
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[avs_response_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `avs_response` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `cvv_response_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `cvv_response_message` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `response_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `state` | One of `checkout`, `processing`, `pending`, `completed`, `failed`, `void`, `invalid` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `status` | One of `checkout`, `processing`, `pending`, `completed`, `failed`, `void`, `invalid` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
          | `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
          | `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
          | `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
          | `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
          | `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
          | `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
          | `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
          | `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
          | `order_store_` | `created_at`, `id`, `name`, `updated_at` |
          | `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
          | `payment_method_` | `active`, `created_at`, `id`, `name`, `position`, `storefront_visible`, `type`, `updated_at` |

          </Accordion>

          **Sort by:** `amount`, `avs_response`, `created_at`, `cvv_response_code`, `cvv_response_message`, `id`, `response_code`, `state`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Payment
        sortable:
        - amount
        - avs_response
        - created_at
        - cvv_response_code
        - cvv_response_message
        - id
        - response_code
        - state
        - status
        - updated_at
      responses:
        '200':
          description: payments found
          content:
            application/json:
              example:
                data:
                - id: py_UkLWZg9DAJ
                  payment_method_id: pm_UkLWZg9DAJ
                  response_code: BGS-343039b69b86
                  number: R1001-P1
                  status: completed
                  amount: '110.00'
                  source_type: credit_card
                  source_id: card_UkLWZg9DAJ
                  source:
                    id: card_UkLWZg9DAJ
                    brand: visa
                    last4: '1111'
                    month: 12
                    year: 2027
                    name: Spree Commerce
                    default: false
                    gateway_payment_profile_id:
                    customer_id:
                    payment_method_id: pm_gbHJdmfrXB
                    metadata: {}
                    created_at: '2026-01-15T12:00:00.000Z'
                    updated_at: '2026-01-15T12:00:00.000Z'
                  metadata: {}
                  avs_response:
                  cvv_response_code:
                  cvv_response_message:
                  gateway_dashboard_payment_url: https://dashboard.bogus.example/payments/BGS-343039b69b86
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  avs_risky: false
                  cvv_risky: false
                  can_void: true
                  can_capture: false
                  captured_amount: '0.00'
                  order_id: or_UkLWZg9DAJ
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
    post:
      summary: Create a payment
      tags:
      - Payments
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Creates a new payment for the order.

        **Required scope:** `write_payments` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const payment = await client.orders.payments.create('or_UkLWZg9DAJ', {
            payment_method_id: 'pm_UkLWZg9DAJ',
            amount: '99.99',
            source_id: 'cc_UkLWZg9DAJ',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /orders/{order_id}/payments -d '{"payment_method_id":"pm_UkLWZg9DAJ","amount":"99.99","source_id":"cc_UkLWZg9DAJ"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      responses:
        '201':
          description: payment created
          content:
            application/json:
              example:
                id: py_gbHJdmfrXB
                payment_method_id: pm_EfhxLZ9ck8
                response_code:
                number: R1002-P1
                status: checkout
                amount: '110.00'
                source_type:
                source_id:
                source:
                metadata: {}
                avs_response:
                cvv_response_code:
                cvv_response_message:
                gateway_dashboard_payment_url:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                avs_risky: false
                cvv_risky: false
                can_void: true
                can_capture: true
                captured_amount: '0.00'
                order_id: or_gbHJdmfrXB
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PaymentCreateParams"
        required: true
  "/api/v3/admin/orders/{order_id}/payments/{id}":
    get:
      summary: Show a payment
      tags:
      - Payments
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns details of a specific payment.

        **Required scope:** `read_payments` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const payment = await client.orders.payments.get('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /orders/{order_id}/payments/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Payment ID
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., payment_method,
          source). Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., amount,status,number,response_code).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: payment found
          content:
            application/json:
              example:
                id: py_UkLWZg9DAJ
                payment_method_id: pm_UkLWZg9DAJ
                response_code: BGS-4a236d40ef07
                number: R1001-P1
                status: completed
                amount: '110.00'
                source_type: credit_card
                source_id: card_UkLWZg9DAJ
                source:
                  id: card_UkLWZg9DAJ
                  brand: visa
                  last4: '1111'
                  month: 12
                  year: 2027
                  name: Spree Commerce
                  default: false
                  gateway_payment_profile_id:
                  customer_id:
                  payment_method_id: pm_gbHJdmfrXB
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                metadata: {}
                avs_response:
                cvv_response_code:
                cvv_response_message:
                gateway_dashboard_payment_url: https://dashboard.bogus.example/payments/BGS-4a236d40ef07
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                avs_risky: false
                cvv_risky: false
                can_void: true
                can_capture: false
                captured_amount: '0.00'
                order_id: or_UkLWZg9DAJ
  "/api/v3/admin/orders/{order_id}/payments/{id}/capture":
    patch:
      summary: Capture a payment
      tags:
      - Payments
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Captures a pending payment, in full or for part of the authorized amount.

        **Required scope:** `write_payments` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const payment = await client.orders.payments.capture('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/payments/{id}/capture -d '{ ...
          }'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Payment ID
        schema:
          type: string
      responses:
        '200':
          description: payment captured
          content:
            application/json:
              example:
                id: py_UkLWZg9DAJ
                payment_method_id: pm_UkLWZg9DAJ
                response_code: BGS-ccc19f06b194
                number: R1001-P1
                status: completed
                amount: '110.00'
                source_type: credit_card
                source_id: card_UkLWZg9DAJ
                source:
                  id: card_UkLWZg9DAJ
                  brand: visa
                  last4: '1111'
                  month: 12
                  year: 2027
                  name: Spree Commerce
                  default: false
                  gateway_payment_profile_id:
                  customer_id:
                  payment_method_id: pm_gbHJdmfrXB
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                metadata: {}
                avs_response:
                cvv_response_code:
                cvv_response_message:
                gateway_dashboard_payment_url: https://dashboard.bogus.example/payments/BGS-ccc19f06b194
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                avs_risky: false
                cvv_risky: false
                can_void: true
                can_capture: false
                captured_amount: '110.00'
                order_id: or_UkLWZg9DAJ
        '422':
          description: capture failed
          content:
            application/json:
              example:
                error:
                  code: processing_error
                  message: 'Bogus Gateway: Forced failure'
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PaymentCaptureParams"
  "/api/v3/admin/orders/{order_id}/payments/{id}/void":
    patch:
      summary: Void a payment
      tags:
      - Payments
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Voids a payment.

        **Required scope:** `write_payments` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const payment = await client.orders.payments.void('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api patch /orders/{order_id}/payments/{id}/void -d '{ ... }'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: order_id
        in: path
        required: true
        description: Order ID
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Payment ID
        schema:
          type: string
      responses:
        '200':
          description: payment voided
          content:
            application/json:
              example:
                id: py_UkLWZg9DAJ
                payment_method_id: pm_UkLWZg9DAJ
                response_code: void-BGS-11f2e975ba0c
                number: R1001-P1
                status: void
                amount: '110.00'
                source_type: credit_card
                source_id: card_UkLWZg9DAJ
                source:
                  id: card_UkLWZg9DAJ
                  brand: visa
                  last4: '1111'
                  month: 12
                  year: 2027
                  name: Spree Commerce
                  default: false
                  gateway_payment_profile_id:
                  customer_id:
                  payment_method_id: pm_gbHJdmfrXB
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                metadata: {}
                avs_response:
                cvv_response_code:
                cvv_response_message:
                gateway_dashboard_payment_url: https://dashboard.bogus.example/payments/void-BGS-11f2e975ba0c
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                avs_risky: false
                cvv_risky: false
                can_void: false
                can_capture: false
                captured_amount: '0.00'
                order_id: or_UkLWZg9DAJ
  "/api/v3/admin/price_lists":
    get:
      summary: List price lists
      tags:
      - Pricing
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the price lists configured for the current store.

        **Required scope:** `read_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: priceLists } = await client.priceLists.list()
      - lang: bash
        label: Spree CLI
        source: spree api get /price_lists
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of name (partial, case-insensitive).
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      - name: sort
        in: query
        required: false
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: 'Comma-separated associations to embed. Supported: `price_rules`.'
        schema:
          type: string
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `catalog_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `ends_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `match_policy` | One of `all`, `any` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `starts_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `status` | One of `draft`, `active`, `inactive`, `scheduled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `catalog_id`, `created_at`, `ends_at`, `id`, `match_policy`, `name`, `position`, `starts_at`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: PriceList
        sortable:
        - catalog_id
        - created_at
        - ends_at
        - id
        - match_policy
        - name
        - position
        - starts_at
        - status
        - updated_at
      responses:
        '200':
          description: price lists found
          content:
            application/json:
              example:
                data:
                - id: pl_UkLWZg9DAJ
                  name: Wholesale
                  description:
                  status: draft
                  position: 1
                  match_policy: all
                  adjust_compare_at: false
                  starts_at:
                  ends_at:
                  deleted_at:
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  price_adjustment_percentage:
                  automatic_pricing: false
                  currently_active: false
                  products_count: 0
                  prices_count: 0
                  price_adjustment_tiers: []
                - id: pl_gbHJdmfrXB
                  name: Holiday
                  description:
                  status: draft
                  position: 2
                  match_policy: all
                  adjust_compare_at: false
                  starts_at:
                  ends_at:
                  deleted_at:
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  price_adjustment_percentage:
                  automatic_pricing: false
                  currently_active: false
                  products_count: 0
                  prices_count: 0
                  price_adjustment_tiers: []
                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/PriceList"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
    post:
      summary: Create a price list
      tags:
      - Pricing
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Creates a new draft price list.

        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Server-to-server one-shot create. Ship the rules that gate the list
          // and the exact per-variant prices in a single request — variants in
          // `prices` implicitly become part of the list (upserted on the unique
          // key `(variant_id, currency, price_list_id)`). Curating whole products
          // goes through `client.priceLists.products` instead.
          const priceList = await client.priceLists.create({
            name: 'EU wholesale',
            description: 'Tiered pricing for verified B2B customers',
            match_policy: 'all',
            starts_at: '2026-06-01T00:00:00Z',
            ends_at: '2026-09-01T00:00:00Z',
            rules: [
              {
                type: 'customer_group_rule',
                preferences: { customer_group_ids: ['cg_aBc123'] },
              },
              {
                type: 'volume_rule',
                preferences: { min_quantity: 10 },
              },
            ],
            prices: [
              {
                variant_id: 'variant_xY9',
                currency: 'USD',
                amount: '19.99',
                compare_at_amount: '24.99',
              },
              {
                variant_id: 'variant_aB7',
                currency: 'USD',
                amount: '21.99',
              },
            ],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /price_lists -d '{"name":"EU wholesale","description":"Tiered
          pricing for verified B2B customers","match_policy":"all","starts_at":"2026-06-01T00:00:00Z","ends_at":"2026-09-01T00:00:00Z","rules":[{"type":"customer_group_rule","preferences":{"customer_group_ids":["cg_aBc123"]}},{"type":"volume_rule","preferences":{"min_quantity":10}}],"prices":[{"variant_id":"variant_xY9","currency":"USD","amount":"19.99","compare_at_amount":"24.99"},{"variant_id":"variant_aB7","currency":"USD","amount":"21.99"}]}'
      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: price list created (server-to-server — rules + prices)
          content:
            application/json:
              example:
                id: pl_EfhxLZ9ck8
                name: EU wholesale
                description:
                status: draft
                position: 3
                match_policy: all
                adjust_compare_at: false
                starts_at:
                ends_at:
                deleted_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                price_adjustment_percentage:
                automatic_pricing: false
                currently_active: false
                products_count: 1
                prices_count: 2
                price_adjustment_tiers: []
              schema:
                "$ref": "#/components/schemas/PriceList"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Name can't be blank
                  details:
                    name:
                    - code: blank
                      message: can't be blank
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PriceListCreateParams"
        required: true
  "/api/v3/admin/price_lists/{id}":
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      summary: Get a price list
      tags:
      - Pricing
      security:
      - api_key: []
        bearer_auth: []
      description: "**Required scope:** `read_products` (for API-key authentication)."
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const priceList = await client.priceLists.get('pl_xxx')
      - lang: bash
        label: Spree CLI
        source: spree api get /price_lists/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: expand
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: price list found
          content:
            application/json:
              example:
                id: pl_UkLWZg9DAJ
                name: Wholesale
                description:
                status: draft
                position: 1
                match_policy: all
                adjust_compare_at: false
                starts_at:
                ends_at:
                deleted_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                price_adjustment_percentage:
                automatic_pricing: false
                currently_active: false
                products_count: 0
                prices_count: 0
                price_adjustment_tiers: []
              schema:
                "$ref": "#/components/schemas/PriceList"
        '404':
          description: price list not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Price list not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update a price list
      tags:
      - Pricing
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Updates a price list. The optional `rules:` array reconciles nested
        STI-typed price rules in a single round-trip — existing rules update
        by `id`, new rules build, missing rules destroy. Mirrors the
        promotion editor's "save the whole thing on Save" pattern.


        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const priceList = await client.priceLists.update('pl_xxx', {
            name: 'Wholesale (Q3)',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /price_lists/{id} -d '{"name":"Wholesale (Q3)"}'
      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: price list updated with nested rules
          content:
            application/json:
              example:
                id: pl_UkLWZg9DAJ
                name: Wholesale (Q3)
                description:
                status: draft
                position: 1
                match_policy: all
                adjust_compare_at: false
                starts_at:
                ends_at:
                deleted_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                price_adjustment_percentage:
                automatic_pricing: false
                currently_active: false
                products_count: 0
                prices_count: 0
                price_adjustment_tiers: []
              schema:
                "$ref": "#/components/schemas/PriceList"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PriceListUpdateParams"
        required: true
    delete:
      summary: Delete a price list
      tags:
      - Pricing
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Soft-deletes the price list. Associated prices are removed asynchronously.

        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.priceLists.delete('pl_xxx')
      - lang: bash
        label: Spree CLI
        source: spree api delete /price_lists/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '204':
          description: price list deleted
  "/api/v3/admin/price_lists/{id}/activate":
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    patch:
      summary: Activate a price list
      tags:
      - Pricing
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Transitions a draft / inactive list to `active`. If `starts_at` is
        in the future the list is marked `scheduled` instead, matching the
        legacy admin behaviour.


        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const priceList = await client.priceLists.activate('pl_xxx')
      - lang: bash
        label: Spree CLI
        source: spree api patch /price_lists/{id}/activate -d '{ ... }'
      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: price list activated
          content:
            application/json:
              example:
                id: pl_UkLWZg9DAJ
                name: Wholesale
                description:
                status: active
                position: 1
                match_policy: all
                adjust_compare_at: false
                starts_at:
                ends_at:
                deleted_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                price_adjustment_percentage:
                automatic_pricing: false
                currently_active: true
                products_count: 0
                prices_count: 0
                price_adjustment_tiers: []
              schema:
                "$ref": "#/components/schemas/PriceList"
  "/api/v3/admin/price_lists/{id}/deactivate":
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    patch:
      summary: Deactivate a price list
      tags:
      - Pricing
      security:
      - api_key: []
        bearer_auth: []
      description: "**Required scope:** `write_products` (for API-key authentication)."
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const priceList = await client.priceLists.deactivate('pl_xxx')
      - lang: bash
        label: Spree CLI
        source: spree api patch /price_lists/{id}/deactivate -d '{ ... }'
      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: price list deactivated
          content:
            application/json:
              example:
                id: pl_UkLWZg9DAJ
                name: Price List 2
                description:
                status: inactive
                position: 1
                match_policy: all
                adjust_compare_at: false
                starts_at:
                ends_at:
                deleted_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                price_adjustment_percentage:
                automatic_pricing: false
                currently_active: false
                products_count: 0
                prices_count: 0
                price_adjustment_tiers: []
              schema:
                "$ref": "#/components/schemas/PriceList"
  "/api/v3/admin/prices":
    get:
      summary: List prices
      tags:
      - Pricing
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Generic prices endpoint covering both base prices and price-list
        overrides. Filter with Ransack: `q[price_list_id_eq]=…`,
        `q[currency_eq]=USD`, `q[price_list_id_null]=true` (base prices only).

        The admin spreadsheet uses this with server-side pagination so it
        scales past the metadata-PATCH path on `/price_lists/:id`.


        **Required scope:** `read_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: prices } = await client.prices.list({
            price_list_id_eq: 'pl_xxx',
            currency_eq: 'USD',
            expand: ['variant'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /prices -d '{"price_list_id_eq":"pl_xxx","currency_eq":"USD","expand":["variant"]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches the variant's SKU, option value or product name, as variant
          search does.
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      - name: sort
        in: query
        required: false
        description: Comma-separated sort keys. Supports e.g. `variant_product_name,variant_id`.
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: 'Comma-separated associations to embed. Supported: `variant`.'
        schema:
          type: string
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[amount_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `compare_at_amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `currency` | One of the `CurrencyCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `min_quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `price_list_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `variant_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[price_list_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `price_list_` | `catalog_id`, `created_at`, `ends_at`, `id`, `match_policy`, `name`, `position`, `starts_at`, `status`, `updated_at` |
          | `variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |
          | `variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
          | `variant_product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |
          | `variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |

          </Accordion>

          **Sort by:** `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Price
        sortable:
        - amount
        - compare_at_amount
        - created_at
        - currency
        - id
        - min_quantity
        - price_list_id
        - updated_at
        - variant_id
      responses:
        '200':
          description: prices found
          content:
            application/json:
              example:
                data:
                - id: price_UkLWZg9DAJ
                  currency: USD
                  amount: '19.99'
                  compare_at_amount:
                  price_list_id:
                  min_quantity: 1
                  variant_id: variant_UkLWZg9DAJ
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                - id: price_gbHJdmfrXB
                  currency: USD
                  amount: '19.99'
                  compare_at_amount:
                  price_list_id:
                  min_quantity: 1
                  variant_id: variant_gbHJdmfrXB
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                - id: price_EfhxLZ9ck8
                  currency: USD
                  amount: '5.00'
                  compare_at_amount:
                  price_list_id: pl_UkLWZg9DAJ
                  min_quantity: 1
                  variant_id: variant_gbHJdmfrXB
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                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/Price"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
    post:
      summary: Create a price
      tags:
      - Pricing
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Creates a single price. Omit `price_list_id` to create a base price.
        For more than a handful of rows, prefer `POST /admin/prices/bulk_upsert`.


        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const price = await client.prices.create({
            variant_id: 'variant_xxx',
            currency: 'USD',
            amount: '19.99',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /prices -d '{"variant_id":"variant_xxx","currency":"USD","amount":"19.99"}'
      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: price created
          content:
            application/json:
              example:
                id: price_uw2YK1rnl0
                currency: EUR
                amount: '9.99'
                compare_at_amount:
                price_list_id:
                min_quantity: 1
                variant_id: variant_EfhxLZ9ck8
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/Price"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PriceCreateParams"
        required: true
  "/api/v3/admin/prices/{id}":
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      summary: Get a price
      tags:
      - Pricing
      security:
      - api_key: []
        bearer_auth: []
      description: "**Required scope:** `read_products` (for API-key authentication)."
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const price = await client.prices.get('price_xxx')
      - lang: bash
        label: Spree CLI
        source: spree api get /prices/{id}
      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: price found
          content:
            application/json:
              example:
                id: price_EfhxLZ9ck8
                currency: USD
                amount: '5.00'
                compare_at_amount:
                price_list_id: pl_UkLWZg9DAJ
                min_quantity: 1
                variant_id: variant_gbHJdmfrXB
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/Price"
        '404':
          description: price not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Price not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update a price
      tags:
      - Pricing
      security:
      - api_key: []
        bearer_auth: []
      description: "**Required scope:** `write_products` (for API-key authentication)."
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const price = await client.prices.update('price_xxx', {
            amount: '12.34',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /prices/{id} -d '{"amount":"12.34"}'
      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: price updated
          content:
            application/json:
              example:
                id: price_EfhxLZ9ck8
                currency: USD
                amount: '12.34'
                compare_at_amount:
                price_list_id: pl_UkLWZg9DAJ
                min_quantity: 1
                variant_id: variant_gbHJdmfrXB
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/Price"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PriceUpdateParams"
        required: true
    delete:
      summary: Delete a price
      tags:
      - Pricing
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Soft-deletes the price (acts_as_paranoid).

        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.prices.delete('price_xxx')
      - lang: bash
        label: Spree CLI
        source: spree api delete /prices/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '204':
          description: price deleted
  "/api/v3/admin/prices/bulk_upsert":
    post:
      summary: Bulk-upsert prices
      tags:
      - Pricing
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Upserts a batch of prices in a single SQL round trip.

        Each row either:
        * targets an existing price by `id`, OR
        * matches on the unique key `(variant_id, currency, price_list_id)` —
          updating the existing row if one exists, creating one otherwise.

        Model callbacks (e.g. PriceHistory) are bypassed; this is a
        bulk-write fast path for the admin spreadsheet. The response
        carries `price_count` — the number of rows touched.


        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { price_count } = await client.prices.bulkUpsert({
            prices: [
              {
                variant_id: 'variant_xxx',
                currency: 'USD',
                price_list_id: 'pl_xxx',
                amount: '11.11',
              },
              {
                variant_id: 'variant_yyy',
                currency: 'USD',
                price_list_id: 'pl_xxx',
                amount: '22.22',
              },
            ],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /prices/bulk_upsert -d '{"prices":[{"variant_id":"variant_xxx","currency":"USD","price_list_id":"pl_xxx","amount":"11.11"},{"variant_id":"variant_yyy","currency":"USD","price_list_id":"pl_xxx","amount":"22.22"}]}'
      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: prices upserted
          content:
            application/json:
              example:
                price_count: 2
              schema:
                type: object
                properties:
                  price_count:
                    type: integer
        '422':
          description: missing prices key
          content:
            application/json:
              example:
                error:
                  code: missing_prices
                  message: prices is required (send an empty array to no-op).
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PriceBulkUpsertParams"
        required: true
  "/api/v3/admin/prices/bulk_destroy":
    delete:
      x-spree-agent: false
      x-spree-agent-reason: Deletes many prices in one call behind a single confirmation;
        delete_resource removes them one at a time.
      summary: Bulk-delete prices
      tags:
      - Pricing
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Soft-deletes each price in `ids`. Returns the count actually destroyed.

        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { price_count } = await client.prices.bulkDestroy({
            ids: ['price_xxx', 'price_yyy'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api delete /prices/bulk_destroy -d '{"ids":["price_xxx","price_yyy"]}'
      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: prices deleted
          content:
            application/json:
              example:
                price_count: 1
              schema:
                type: object
                properties:
                  price_count:
                    type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PriceBulkDestroyParams"
        required: true
  "/api/v3/admin/products/{product_id}/custom_fields":
    get:
      summary: List product custom fields
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the product's custom field values.

        **Required scope:** `read_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: customFields } = await client.products.customFields.list('prod_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /products/{product_id}/custom_fields
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: product_id
        in: path
        required: true
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., custom_field_definition).
          Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., key,value,namespace).
          id is always included.
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: CustomField
        sortable:
        - created_at
        - id
        - updated_at
      responses:
        '200':
          description: custom fields found
          content:
            application/json:
              example:
                data:
                - id: cf_UkLWZg9DAJ
                  label: Title
                  field_type: short_text
                  key: custom.title
                  value: wool
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  storefront_visible: true
                  custom_field_definition_id: cfdef_UkLWZg9DAJ
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
    post:
      summary: Create a product custom field
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.

        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const customField = await client.products.customFields.create('prod_UkLWZg9DAJ', {
            custom_field_definition_id: 'cfdef_AbC123XyZ',
            value: 'wool',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /products/{product_id}/custom_fields -d '{"custom_field_definition_id":"cfdef_AbC123XyZ","value":"wool"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: product_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: custom field created
          content:
            application/json:
              example:
                id: cf_gbHJdmfrXB
                label: Description
                field_type: long_text
                key: custom.description
                value: A longer description
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                storefront_visible: true
                custom_field_definition_id: cfdef_gbHJdmfrXB
        '422':
          description: duplicate definition for the same product
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Custom field definition has already been taken
                  details:
                    custom_field_definition_id:
                    - value: 1
                      code: taken
                      message: has already been taken
                      specific: false
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CustomFieldCreateParams"
        required: true
  "/api/v3/admin/products/{product_id}/custom_fields/{id}":
    get:
      summary: Show a product custom field
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: "**Required scope:** `read_products` (for API-key authentication)."
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const customField = await client.products.customFields.get('prod_UkLWZg9DAJ', 'cf_AbC123XyZ')
      - lang: bash
        label: Spree CLI
        source: spree api get /products/{product_id}/custom_fields/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: product_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., custom_field_definition).
          Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., key,value,namespace).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: custom field found
          content:
            application/json:
              example:
                id: cf_UkLWZg9DAJ
                label: Title
                field_type: short_text
                key: custom.title
                value: wool
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                storefront_visible: true
                custom_field_definition_id: cfdef_UkLWZg9DAJ
    patch:
      summary: Update a product custom field
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.

        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const customField = await client.products.customFields.update('prod_UkLWZg9DAJ', 'cf_AbC123XyZ', {
            value: 'cotton',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /products/{product_id}/custom_fields/{id} -d '{"value":"cotton"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: product_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: custom field updated
          content:
            application/json:
              example:
                id: cf_UkLWZg9DAJ
                label: Title
                field_type: short_text
                key: custom.title
                value: cotton
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                storefront_visible: true
                custom_field_definition_id: cfdef_UkLWZg9DAJ
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CustomFieldUpdateParams"
        required: true
    delete:
      summary: Delete a product custom field
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: "**Required scope:** `write_products` (for API-key authentication)."
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.products.customFields.delete('prod_UkLWZg9DAJ', 'cf_AbC123XyZ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /products/{product_id}/custom_fields/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: product_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: custom field deleted
  "/api/v3/admin/products/{product_id}/digital_assets":
    parameters:
    - name: product_id
      in: path
      required: true
      description: Product ID
      schema:
        type: string
    get:
      summary: List product digital assets
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the downloadable files attached to the product's variants, oldest first.

        **Required scope:** `read_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: digitalAssets } = await client.products.digitalAssets.list('prod_86Rf07xd4z')
      - lang: bash
        label: Spree CLI
        source: spree api get /products/{product_id}/digital_assets
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: DigitalAsset
        sortable:
        - created_at
        - id
        - updated_at
      responses:
        '200':
          description: digital assets found
          content:
            application/json:
              example:
                data:
                - id: dig_UkLWZg9DAJ
                  variant_id: variant_UkLWZg9DAJ
                  filename: thinking-cat.jpg
                  content_type: image/jpeg
                  authorized_clicks:
                  authorized_days:
                  byte_size: 18090
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  provider_type:
                  provider_name: File
                  download_url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJ0Z252N2l0MG55YnkwbHhkczg5Y2hteTd6aXlvIiwiZGlzcG9zaXRpb24iOiJhdHRhY2htZW50OyBmaWxlbmFtZT1cInRoaW5raW5nLWNhdC5qcGdcIjsgZmlsZW5hbWUqPVVURi04Jyd0aGlua2luZy1jYXQuanBnIiwiY29udGVudF90eXBlIjoiaW1hZ2UvanBlZyIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl9rZXkifX0=--06a160c64f398ed4eb70327ef6932eaf662f98d7/thinking-cat.jpg
                  effective_authorized_clicks: 5
                  effective_authorized_days: 7
                  provider_settings: {}
                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/DigitalAsset"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
    post:
      summary: Create a product digital asset
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Attaches a downloadable file to one of the product's variants (the
        default variant when `variant_id` is omitted). Upload the file first
        through `POST /api/v3/admin/files` with `visibility: 'private'`, then
        send its `signed_id` here. A provider-backed asset sends
        `provider_type` and `provider_settings` instead of a file.


        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // `signed_id` comes from `files.upload()` with `visibility: 'private'`.
          const digitalAsset = await client.products.digitalAssets.create('prod_86Rf07xd4z', {
            signed_id: 'eyJfcmFpbHMiOnsiZGF0YSI6MTIzfX0=--abc123',
            authorized_clicks: 5,
            authorized_days: 30,
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /products/{product_id}/digital_assets -d '{"signed_id":"eyJfcmFpbHMiOnsiZGF0YSI6MTIzfX0=--abc123","authorized_clicks":5,"authorized_days":30}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '201':
          description: digital asset created
          content:
            application/json:
              example:
                id: dig_gbHJdmfrXB
                variant_id: variant_UkLWZg9DAJ
                filename: manual.pdf
                content_type: image/jpeg
                authorized_clicks: 5
                authorized_days: 30
                byte_size: 18090
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                provider_type:
                provider_name: File
                download_url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJhOXR0cGNpbmxxbThvbmtlNHM1NmI2Y3gxMWVzIiwiZGlzcG9zaXRpb24iOiJhdHRhY2htZW50OyBmaWxlbmFtZT1cIm1hbnVhbC5wZGZcIjsgZmlsZW5hbWUqPVVURi04JydtYW51YWwucGRmIiwiY29udGVudF90eXBlIjoiaW1hZ2UvanBlZyIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl9rZXkifX0=--0df5c2167c42cdda6a5f6639d3ddc1b4473c5a81/manual.pdf
                effective_authorized_clicks: 5
                effective_authorized_days: 30
                provider_settings: {}
              schema:
                "$ref": "#/components/schemas/DigitalAsset"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/DigitalAssetCreateParams"
        required: true
  "/api/v3/admin/products/{product_id}/digital_assets/{id}":
    parameters:
    - name: product_id
      in: path
      required: true
      description: Product ID
      schema:
        type: string
    - name: id
      in: path
      required: true
      description: Digital asset ID
      schema:
        type: string
    patch:
      summary: Update a product digital asset
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Changes an asset's download limits, or replaces its file with a new
        private `signed_id`. Links customers already received keep working and
        serve the new file.


        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // `null` falls back to the store's download settings.
          const digitalAsset = await client.products.digitalAssets.update(
            'prod_86Rf07xd4z',
            'dig_k5nR8xLqPz',
            { authorized_clicks: 10, authorized_days: null },
          )
      - lang: bash
        label: Spree CLI
        source: spree api patch /products/{product_id}/digital_assets/{id} -d '{"authorized_clicks":10,"authorized_days":null}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: digital asset updated
          content:
            application/json:
              example:
                id: dig_UkLWZg9DAJ
                variant_id: variant_UkLWZg9DAJ
                filename: thinking-cat.jpg
                content_type: image/jpeg
                authorized_clicks: 10
                authorized_days:
                byte_size: 18090
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                provider_type:
                provider_name: File
                download_url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiIwZXp6d3IzMzE3ajRoem9kc3Awc2czN3EzMnhzIiwiZGlzcG9zaXRpb24iOiJhdHRhY2htZW50OyBmaWxlbmFtZT1cInRoaW5raW5nLWNhdC5qcGdcIjsgZmlsZW5hbWUqPVVURi04Jyd0aGlua2luZy1jYXQuanBnIiwiY29udGVudF90eXBlIjoiaW1hZ2UvanBlZyIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl9rZXkifX0=--da799713969a4775b10b6055f685e92f410f5176/thinking-cat.jpg
                effective_authorized_clicks: 10
                effective_authorized_days: 7
                provider_settings: {}
              schema:
                "$ref": "#/components/schemas/DigitalAsset"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/DigitalAssetUpdateParams"
        required: true
  "/api/v3/admin/products/{product_id}/translations":
    get:
      summary: List product translations
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the full translation matrix for the product: the source value and content type per translatable field, plus the translated value for every supported locale.

        **Required scope:** `read_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Source values and every locale's translations, including the product's variants and options.
          const translations = await client.products.translations.get('prod_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /products/{product_id}/translations
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: product_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: translations found
          content:
            application/json:
              example:
                data:
                  resource_id: prod_UkLWZg9DAJ
                  resource_type: product
                  translations:
                    de:
                      name: Espressomaschine
                      description:
                      slug: espressomaschine
                      meta_description:
                      meta_title:
                      translated_field_count: 2
                    fr:
                      name:
                      description:
                      slug:
                      meta_description:
                      meta_title:
                      translated_field_count: 0
                  fields:
                  - key: name
                    type: string
                    source: Espresso Machine
                  - key: description
                    type: html
                    source: |-
                      Atque esse occaecati recusandae quam sit blanditiis accusamus. Et temporibus optio quos est esse nobis odit nihil. Magnam quo illum voluptas dolorum quidem. Modi rerum labore praesentium laborum veritatis iusto.
                      Tempora exercitationem sed vero itaque nihil odio distinctio explicabo. Corporis nesciunt minus veritatis beatae quaerat facilis similique eius. Esse dolores suscipit iusto totam velit ipsa.
                      Aut saepe quibusdam mollitia amet. Eius beatae facilis asperiores maiores. Fuga doloremque provident perspiciatis natus a quaerat reprehenderit occaecati. Eius deserunt commodi placeat delectus.
                      Consequatur quas ipsum voluptas quis. Vel cumque molestiae magnam optio. Recusandae eum cum sequi autem fugiat animi tenetur.
                  - key: slug
                    type: string
                    source: espresso-machine
                  - key: meta_description
                    type: string
                    source:
                  - key: meta_title
                    type: string
                    source:
                  default_locale: en
                  supported_locales:
                  - de
                  - en
                  - fr
  "/api/v3/admin/products":
    get:
      summary: List products
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a paginated list of products for the current store.

        **Required scope:** `read_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: products } = await client.products.list({
            search: 'shirt',
            status_eq: 'active',
            sort: '-created_at',
            limit: 25,
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /products -d '{"search":"shirt","status_eq":"active","sort":"-created_at","limit":25}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches product name or variant SKU (partial, case-insensitive),
          and the store's searchable custom fields.
      - name: q[ascend_by_price]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `ascend_by_price`.
      - name: q[descend_by_price]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `descend_by_price`.
      - name: q[in_categories][]
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        description: Applies `in_categories` to the given value.
      - name: q[in_category]
        in: query
        required: false
        schema:
          type: string
        description: Applies `in_category` to the given value.
      - name: q[in_collection]
        in: query
        required: false
        schema:
          type: string
        description: Applies `in_collection` to the given value.
      - name: q[in_stock]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `in_stock`.
      - name: q[in_taxon]
        in: query
        required: false
        schema:
          type: string
        description: Applies `in_taxon` to the given value.
      - name: q[not_discontinued]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `not_discontinued`.
      - name: q[out_of_stock]
        in: query
        required: false
        schema:
          type: boolean
        description: Set to `true` to apply `out_of_stock`.
      - name: q[price_between][]
        in: query
        required: false
        schema:
          type: array
          items:
            type: number
          minItems: 2
          maxItems: 2
        description: Applies `price_between` to the given value.
      - name: q[price_gte]
        in: query
        required: false
        schema:
          type: number
        description: Applies `price_gte` to the given value.
      - name: q[price_lte]
        in: query
        required: false
        schema:
          type: number
        description: Applies `price_lte` to the given value.
      - name: q[search_by_name]
        in: query
        required: false
        schema:
          type: string
        description: Applies `search_by_name` to the given value.
      - name: q[with_option_value_ids][]
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        description: Applies `with_option_value_ids` to the given value.
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: sort
        in: query
        required: false
        description: Sort field (e.g., name, -name, price, -price, best_selling)
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., variants, media,
          option_types, categories). Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price,status).
          id is always included.
        schema:
          type: string
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `available_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `description` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `slug` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `status` | One of `draft`, `active`, `archived`, `proposed`, `rejected` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          <Accordion title="Filters through associations">

          Prefix an associated record's attribute with the association, as in `q[categories_id_eq]`. The same predicates apply.

          | Prefix | Attributes |
          |---|---|
          | `categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |
          | `categories_parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |
          | `channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
          | `collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |
          | `default_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |
          | `default_variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
          | `default_variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
          | `default_variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `default_variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
          | `labels_` | `created_at`, `id`, `name`, `updated_at` |
          | `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |
          | `product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |
          | `product_type_` | `created_at`, `id`, `name`, `updated_at` |
          | `product_type_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |
          | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `store_` | `created_at`, `id`, `name`, `updated_at` |
          | `tags_` | `created_at`, `id`, `name`, `updated_at` |
          | `variants_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |
          | `variants_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
          | `variants_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
          | `variants_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
          | `variants_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |

          </Accordion>

          Also filters and sorts on the store's searchable custom fields, as `q[cf_<namespace>_<key>_<predicate>]` and `sort=cf_<namespace>_<key>`.

          **Sort by:** `available_on`, `best_selling`, `created_at`, `description`, `discontinue_on`, `id`, `manual`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Product
        sortable:
        - available_on
        - best_selling
        - created_at
        - description
        - discontinue_on
        - id
        - manual
        - name
        - price
        - seller_id
        - slug
        - status
        - updated_at
        custom_fields: true
      responses:
        '200':
          description: products found
          content:
            application/json:
              example:
                data:
                - id: prod_UkLWZg9DAJ
                  name: Product 1296550
                  slug: product-1296550
                  meta_title:
                  meta_description:
                  meta_keywords:
                  variant_count: 1
                  available_on:
                  preorder_ships_at:
                  purchasable: true
                  preorder: false
                  in_stock: false
                  backorderable: true
                  available: true
                  description: Saepe quas nemo facilis nam. Voluptatem facere nam
                    impedit sunt minus possimus totam ullam. Pariatur ullam sed tenetur
                    quibusdam deleniti.
                  description_html: Saepe quas nemo facilis nam. Voluptatem facere
                    nam impedit sunt minus possimus totam ullam. Pariatur ullam sed
                    tenetur quibusdam deleniti.
                  default_variant_id: variant_UkLWZg9DAJ
                  buy_box_variant_id: variant_UkLWZg9DAJ
                  thumbnail_url:
                  tags: []
                  price:
                    id: price_UkLWZg9DAJ
                    currency: USD
                    amount: '19.99'
                    compare_at_amount:
                    price_list_id:
                    min_quantity: 1
                    variant_id: variant_UkLWZg9DAJ
                    created_at: '2026-01-15T12:00:00.000Z'
                    updated_at: '2026-01-15T12:00:00.000Z'
                  original_price:
                  seller_id:
                  external_references: {}
                  status: active
                  metadata: {}
                  deleted_at:
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  delivery_profile_id: fp_UkLWZg9DAJ
                  seller_name:
                  product_type_id:
                  tax_category_id: taxcat_UkLWZg9DAJ
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Product"
                  meta:
                    "$ref": "#/components/schemas/PaginationMeta"
                required:
                - data
                - meta
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    post:
      summary: Create a product
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Creates a new product. Supports nested variants with prices and option types.

        Option types and values are auto-created if they don't exist.
        Prices are upserted by currency. Stock items are upserted by stock location.


        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const product = await client.products.create({
            name: 'Premium T-Shirt',
            // Rich text: send HTML. Reads return this as plain text, plus
            // `description_html` with the markup.
            description: '<p>Soft, organic cotton.</p>',
            status: 'active',
            variants: [
              {
                sku: 'TSHIRT-S-NAVY',
                options: [
                  { name: 'size', value: 'Small' },
                  { name: 'color', value: 'navy' },
                ],
                prices: [
                  { currency: 'USD', amount: '29.99' },
                  { currency: 'EUR', amount: '27.99' },
                ],
                stock_levels: [{ stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 50 }],
              },
              {
                sku: 'TSHIRT-M-NAVY',
                options: [
                  { name: 'size', value: 'Medium' },
                  { name: 'color', value: 'navy' },
                ],
                prices: [{ currency: 'USD', amount: '29.99' }],
                stock_levels: [{ stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 30 }],
              },
            ],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /products -d '{"name":"Premium T-Shirt","description":"<p>Soft,
          organic cotton.</p>","status":"active","variants":[{"sku":"TSHIRT-S-NAVY","options":[{"name":"size","value":"Small"},{"name":"color","value":"navy"}],"prices":[{"currency":"USD","amount":"29.99"},{"currency":"EUR","amount":"27.99"}],"stock_levels":[{"stock_location_id":"sloc_UkLWZg9DAJ","count_on_hand":50}]},{"sku":"TSHIRT-M-NAVY","options":[{"name":"size","value":"Medium"},{"name":"color","value":"navy"}],"prices":[{"currency":"USD","amount":"29.99"}],"stock_levels":[{"stock_location_id":"sloc_UkLWZg9DAJ","count_on_hand":30}]}]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '201':
          description: product created
          content:
            application/json:
              example:
                id: prod_gbHJdmfrXB
                name: New Product
                slug: new-product
                meta_title:
                meta_description:
                meta_keywords:
                variant_count: 0
                available_on:
                preorder_ships_at:
                purchasable: false
                preorder: false
                in_stock: false
                backorderable: false
                available: false
                description:
                description_html:
                default_variant_id: variant_gbHJdmfrXB
                buy_box_variant_id: variant_gbHJdmfrXB
                thumbnail_url:
                tags: []
                price:
                original_price:
                seller_id:
                external_references: {}
                status: draft
                metadata: {}
                deleted_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                delivery_profile_id: fp_UkLWZg9DAJ
                seller_name:
                product_type_id:
                tax_category_id:
              schema:
                "$ref": "#/components/schemas/Product"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Name can't be blank
                  details:
                    name:
                    - code: blank
                      message: can't be blank
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProductCreateParams"
        required: true
  "/api/v3/admin/products/{id}":
    get:
      summary: Get a product
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a single product by ID.

        **Required scope:** `read_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const product = await client.products.get('prod_86Rf07xd4z', {
            expand: ['variants', 'option_types'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /products/{id} -d '{"expand":["variants","option_types"]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Product ID (e.g., prod_xxx)
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., variants, media,
          option_types, categories). Use dot notation for nested expand (max 4 levels).
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include (e.g., name,slug,price,status).
          id is always included.
        schema:
          type: string
      responses:
        '200':
          description: product found
          content:
            application/json:
              example:
                id: prod_UkLWZg9DAJ
                name: Product 1332061
                slug: product-1332061
                meta_title:
                meta_description:
                meta_keywords:
                variant_count: 1
                available_on:
                preorder_ships_at:
                purchasable: true
                preorder: false
                in_stock: false
                backorderable: true
                available: true
                description: Illo error explicabo cupiditate consequatur. Et expedita
                  velit laborum iure. Harum sit eaque nam ipsam maiores.
                description_html: Illo error explicabo cupiditate consequatur. Et
                  expedita velit laborum iure. Harum sit eaque nam ipsam maiores.
                default_variant_id: variant_UkLWZg9DAJ
                buy_box_variant_id: variant_UkLWZg9DAJ
                thumbnail_url:
                tags: []
                price:
                  id: price_UkLWZg9DAJ
                  currency: USD
                  amount: '19.99'
                  compare_at_amount:
                  price_list_id:
                  min_quantity: 1
                  variant_id: variant_UkLWZg9DAJ
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                original_price:
                seller_id:
                external_references: {}
                status: active
                metadata: {}
                deleted_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                delivery_profile_id: fp_UkLWZg9DAJ
                seller_name:
                product_type_id:
                tax_category_id: taxcat_UkLWZg9DAJ
              schema:
                "$ref": "#/components/schemas/Product"
        '404':
          description: product not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Product not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update a product
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Updates a product. Only provided fields are updated.

        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const product = await client.products.update('prod_86Rf07xd4z', {
            name: 'Updated Name',
            status: 'active',
            tags: ['eco', 'sale'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /products/{id} -d '{"name":"Updated Name","status":"active","tags":["eco","sale"]}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Product ID
        schema:
          type: string
      responses:
        '200':
          description: product updated
          content:
            application/json:
              example:
                id: prod_UkLWZg9DAJ
                name: Updated Name
                slug: product-1355339
                meta_title:
                meta_description:
                meta_keywords:
                variant_count: 1
                available_on:
                preorder_ships_at:
                purchasable: true
                preorder: false
                in_stock: false
                backorderable: true
                available: true
                description: Laborum nostrum nemo fugit temporibus consectetur omnis.
                  Necessitatibus voluptas ut delectus aperiam incidunt tenetur. Alias
                  at perspiciatis laborum similique. Fugit adipisci iure porro architecto
                  odit. Alias enim quis rem reprehenderit temporibus. Hic quae rem
                  aspernatur tempore in. Praesentium assumenda sequi quis quasi. Laboriosam
                  est tempore doloribus cumque inventore vero laborum minus. Reiciendis
                  autem quia eligendi possimus beatae enim. Impedit nemo quae odit
                  dolor velit possimus commodi. Sequi ullam dolorum odio at quam vitae.
                  Corporis ipsa alias tempora accusantium. Adipisci sapiente illum
                  id voluptatum aut illo tempora.
                description_html: |-
                  Laborum nostrum nemo fugit temporibus consectetur omnis. Necessitatibus voluptas ut delectus aperiam incidunt tenetur. Alias at perspiciatis laborum similique. Fugit adipisci iure porro architecto odit.
                  Alias enim quis rem reprehenderit temporibus. Hic quae rem aspernatur tempore in. Praesentium assumenda sequi quis quasi. Laboriosam est tempore doloribus cumque inventore vero laborum minus. Reiciendis autem quia eligendi possimus beatae enim.
                  Impedit nemo quae odit dolor velit possimus commodi. Sequi ullam dolorum odio at quam vitae. Corporis ipsa alias tempora accusantium. Adipisci sapiente illum id voluptatum aut illo tempora.
                default_variant_id: variant_UkLWZg9DAJ
                buy_box_variant_id: variant_UkLWZg9DAJ
                thumbnail_url:
                tags: []
                price:
                  id: price_UkLWZg9DAJ
                  currency: USD
                  amount: '19.99'
                  compare_at_amount:
                  price_list_id:
                  min_quantity: 1
                  variant_id: variant_UkLWZg9DAJ
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                original_price:
                seller_id:
                external_references: {}
                status: active
                metadata: {}
                deleted_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                delivery_profile_id: fp_UkLWZg9DAJ
                seller_name:
                product_type_id:
                tax_category_id: taxcat_UkLWZg9DAJ
              schema:
                "$ref": "#/components/schemas/Product"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Name can't be blank
                  details:
                    name:
                    - code: blank
                      message: can't be blank
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProductUpdateParams"
        required: true
    delete:
      summary: Delete a product
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Soft-deletes a product.

        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.products.delete('prod_86Rf07xd4z')
      - lang: bash
        label: Spree CLI
        source: spree api delete /products/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Product ID
        schema:
          type: string
      responses:
        '204':
          description: product deleted
        '422':
          description: deletion refused by a store rule
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: This product is under an active supplier contract.
                  details:
                    base:
                    - code: under_contract
                      message: This product is under an active supplier contract.
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/admin/products/{id}/clone":
    parameters:
    - name: id
      in: path
      required: true
      description: Product ID
      schema:
        type: string
    post:
      summary: Clone a product
      tags:
      - Products
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const copy = await client.products.clone('prod_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api post /products/{id}/clone -d '{ ... }'
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Creates a draft copy of a product, named "COPY OF …", with its variants,
        prices, stock locations, images, categories, channels and tags; stock on
        hand starts at zero. Use it to start a similar product from an existing
        one instead of building it from scratch.


        **Required scope:** `write_products` (for API-key authentication).
      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: product cloned
          content:
            application/json:
              example:
                id: prod_gbHJdmfrXB
                name: COPY OF Product 1462357
                slug: copy-of-product-1462357
                meta_title:
                meta_description:
                meta_keywords:
                variant_count: 1
                available_on:
                preorder_ships_at:
                purchasable: true
                preorder: false
                in_stock: false
                backorderable: true
                available: false
                description: Dolore facere hic laboriosam sapiente nobis. Doloribus
                  deleniti quasi esse aliquid voluptatem. Rem voluptate omnis suscipit
                  adipisci laudantium. Deleniti error dolorum ratione dolor assumenda
                  iusto. Laborum non rem sapiente temporibus quam inventore. Voluptatum
                  magnam hic molestias laudantium necessitatibus. Totam ducimus provident
                  aliquam repellendus nam maxime error natus. Ex aspernatur nostrum
                  deserunt maxime quis occaecati expedita dolore. Debitis est laboriosam
                  modi aspernatur cumque. Sapiente ab corrupti quos doloremque eius.
                  Laborum officiis culpa voluptate fuga sed. Nemo possimus vel architecto
                  quo modi. Velit aut non iusto exercitationem nostrum nemo. Velit
                  illo nisi quaerat perspiciatis facilis temporibus quae esse.
                description_html: |-
                  Dolore facere hic laboriosam sapiente nobis. Doloribus deleniti quasi esse aliquid voluptatem. Rem voluptate omnis suscipit adipisci laudantium.
                  Deleniti error dolorum ratione dolor assumenda iusto. Laborum non rem sapiente temporibus quam inventore. Voluptatum magnam hic molestias laudantium necessitatibus. Totam ducimus provident aliquam repellendus nam maxime error natus.
                  Ex aspernatur nostrum deserunt maxime quis occaecati expedita dolore. Debitis est laboriosam modi aspernatur cumque. Sapiente ab corrupti quos doloremque eius.
                  Laborum officiis culpa voluptate fuga sed. Nemo possimus vel architecto quo modi. Velit aut non iusto exercitationem nostrum nemo. Velit illo nisi quaerat perspiciatis facilis temporibus quae esse.
                default_variant_id: variant_gbHJdmfrXB
                buy_box_variant_id: variant_gbHJdmfrXB
                thumbnail_url:
                tags: []
                price:
                  id: price_gbHJdmfrXB
                  currency: USD
                  amount: '19.99'
                  compare_at_amount:
                  price_list_id:
                  min_quantity: 1
                  variant_id: variant_gbHJdmfrXB
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                original_price:
                seller_id:
                external_references: {}
                status: draft
                metadata: {}
                deleted_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                delivery_profile_id: fp_UkLWZg9DAJ
                seller_name:
                product_type_id:
                tax_category_id: taxcat_UkLWZg9DAJ
              schema:
                "$ref": "#/components/schemas/Product"
  "/api/v3/admin/products/bulk_status_update":
    post:
      x-spree-agent: false
      x-spree-agent-reason: Writes the status column for many products at once, skipping
        the status workflows and their events; products_activate, products_archive and
        products_draft run them.
      summary: Bulk-update product status
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Sets `status` on each product in `ids`. Reindexes the affected products
        for search. Cross-store IDs are silently dropped. Returns counts.


        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const result = await client.products.bulkStatusUpdate({
            ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
            status: 'archived',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /products/bulk_status_update -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"status":"archived"}'
      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: cross-store products silently dropped
          content:
            application/json:
              example:
                product_count: 0
                status: archived
              schema:
                type: object
                properties:
                  product_count:
                    type: integer
                  status:
                    type: string
        '422':
          description: invalid status
          content:
            application/json:
              example:
                error:
                  code: invalid_status
                  message: Invalid status
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProductBulkStatusParams"
        required: true
  "/api/v3/admin/products/bulk_add_to_categories":
    post:
      summary: Bulk-add products to categories
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Attaches each product in `ids` to every category (category) in `category_ids`.
        Categories from sibling stores are silently ignored.


        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const result = await client.products.bulkAddToCategories({
            ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
            category_ids: ['cat_AbC123XyZ'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /products/bulk_add_to_categories -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"category_ids":["cat_AbC123XyZ"]}'
      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: products added to categories
          content:
            application/json:
              example:
                product_count: 1
                category_count: 1
              schema:
                type: object
                properties:
                  product_count:
                    type: integer
                  category_count:
                    type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProductBulkCategoriesParams"
        required: true
  "/api/v3/admin/products/bulk_remove_from_categories":
    post:
      summary: Bulk-remove products from categories
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Detaches each product in `ids` from every category in `category_ids`.

        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const result = await client.products.bulkRemoveFromCategories({
            ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
            category_ids: ['cat_AbC123XyZ'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /products/bulk_remove_from_categories -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"category_ids":["cat_AbC123XyZ"]}'
      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: products removed from categories
          content:
            application/json:
              example:
                product_count: 1
                category_count: 1
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProductBulkCategoriesParams"
        required: true
  "/api/v3/admin/products/bulk_add_to_collections":
    post:
      summary: Bulk-add products to collections
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Attaches each product in `ids` to every manual collection in `collection_ids`.
        Automatic (rule-based) and sibling-store collections are silently ignored.


        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const result = await client.products.bulkAddToCollections({
            ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
            collection_ids: ['coll_AbC123XyZq'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /products/bulk_add_to_collections -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"collection_ids":["coll_AbC123XyZq"]}'
      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: products added to collections
          content:
            application/json:
              example:
                product_count: 1
                collection_count: 1
              schema:
                type: object
                properties:
                  product_count:
                    type: integer
                  collection_count:
                    type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProductBulkCollectionsParams"
        required: true
  "/api/v3/admin/products/bulk_remove_from_collections":
    post:
      summary: Bulk-remove products from collections
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Detaches each product in `ids` from every collection in `collection_ids`.

        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const result = await client.products.bulkRemoveFromCollections({
            ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
            collection_ids: ['coll_AbC123XyZq'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /products/bulk_remove_from_collections -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"collection_ids":["coll_AbC123XyZq"]}'
      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: products removed from collections
          content:
            application/json:
              example:
                product_count: 1
                collection_count: 1
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProductBulkCollectionsParams"
        required: true
  "/api/v3/admin/products/bulk_add_to_channels":
    post:
      summary: Bulk-add products to channels
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —
        re-publishing on an existing channel is a no-op. Channels from sibling stores
        are silently ignored.


        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const result = await client.products.bulkAddToChannels({
            ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
            channel_ids: ['channel_AbC123XyZ'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /products/bulk_add_to_channels -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"channel_ids":["channel_AbC123XyZ"]}'
      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: products published on channels
          content:
            application/json:
              example:
                product_count: 1
                channel_count: 1
              schema:
                type: object
                properties:
                  product_count:
                    type: integer
                  channel_count:
                    type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProductBulkChannelsParams"
        required: true
  "/api/v3/admin/products/bulk_remove_from_channels":
    post:
      summary: Bulk-remove products from channels
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Unpublishes each product in `ids` from every channel in `channel_ids`.

        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const result = await client.products.bulkRemoveFromChannels({
            ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
            channel_ids: ['channel_AbC123XyZ'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /products/bulk_remove_from_channels -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"channel_ids":["channel_AbC123XyZ"]}'
      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: products unpublished from channels
          content:
            application/json:
              example:
                product_count: 1
                channel_count: 1
                removed: 1
              schema:
                type: object
                properties:
                  product_count:
                    type: integer
                  channel_count:
                    type: integer
                  removed:
                    type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProductBulkChannelsParams"
        required: true
  "/api/v3/admin/products/bulk_add_tags":
    post:
      summary: Bulk-add tags to products
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.

        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const result = await client.products.bulkAddTags({
            ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
            tags: ['summer', 'sale'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /products/bulk_add_tags -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"tags":["summer","sale"]}'
      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: tags added
          content:
            application/json:
              example:
                product_count: 1
                tag_count: 2
              schema:
                type: object
                properties:
                  product_count:
                    type: integer
                  tag_count:
                    type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/BulkTagsParams"
        required: true
  "/api/v3/admin/products/bulk_remove_tags":
    post:
      summary: Bulk-remove tags from products
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Removes each tag in `tags` from every product in `ids`.

        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const result = await client.products.bulkRemoveTags({
            ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
            tags: ['summer'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /products/bulk_remove_tags -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"tags":["summer"]}'
      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: tags removed
          content:
            application/json:
              example:
                product_count: 1
                tag_count: 1
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/BulkTagsParams"
        required: true
  "/api/v3/admin/products/bulk_destroy":
    delete:
      x-spree-agent: false
      x-spree-agent-reason: Deletes many products in one call behind a single confirmation;
        delete_resource removes them one at a time.
      summary: Bulk-delete products
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Soft-deletes each product in `ids`. Returns the count actually destroyed.

        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const result = await client.products.bulkDestroy({
            ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
          })
      - lang: bash
        label: Spree CLI
        source: spree api delete /products/bulk_destroy -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"]}'
      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: products deleted
          content:
            application/json:
              example:
                product_count: 1
              schema:
                type: object
                properties:
                  product_count:
                    type: integer
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProductBulkDestroyParams"
        required: true
  "/api/v3/admin/products/{id}/approve":
    parameters:
    - name: id
      in: path
      required: true
      description: Product ID
      schema:
        type: string
    patch:
      summary: Approve a submitted product
      tags:
      - Products
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const product = await client.products.approve('prod_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api patch /products/{id}/approve -d '{ ... }'
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Puts a product a seller submitted for review on sale, and closes the
        submission. Only a product awaiting review can be approved.

        **Required scope:** `write_products` (for API-key authentication).
      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: product approved
          content:
            application/json:
              example:
                id: prod_gbHJdmfrXB
                name: Product 1538682
                slug: product-1538682
                meta_title:
                meta_description:
                meta_keywords:
                variant_count: 1
                available_on:
                preorder_ships_at:
                purchasable: true
                preorder: false
                in_stock: false
                backorderable: true
                available: true
                description: Eligendi minus placeat hic culpa. Explicabo ea et earum
                  dolor facilis pariatur dolores recusandae. Placeat ut qui optio
                  a veritatis. Ipsam ex delectus reiciendis dolorum cupiditate. Consectetur
                  perferendis blanditiis sunt itaque. Velit odio aliquid hic accusamus
                  ipsa autem quasi. Repellat deserunt officia nobis aliquid sint iusto
                  officiis. Repudiandae natus vitae dolore quam accusamus magnam.
                  Itaque maxime voluptatem cupiditate ratione odit porro sed. Asperiores
                  aliquid dicta consequuntur eum quo. Deleniti recusandae laborum
                  cumque mollitia nisi exercitationem dignissimos.
                description_html: |-
                  Eligendi minus placeat hic culpa. Explicabo ea et earum dolor facilis pariatur dolores recusandae. Placeat ut qui optio a veritatis.
                  Ipsam ex delectus reiciendis dolorum cupiditate. Consectetur perferendis blanditiis sunt itaque. Velit odio aliquid hic accusamus ipsa autem quasi.
                  Repellat deserunt officia nobis aliquid sint iusto officiis. Repudiandae natus vitae dolore quam accusamus magnam. Itaque maxime voluptatem cupiditate ratione odit porro sed. Asperiores aliquid dicta consequuntur eum quo. Deleniti recusandae laborum cumque mollitia nisi exercitationem dignissimos.
                default_variant_id: variant_gbHJdmfrXB
                buy_box_variant_id: variant_gbHJdmfrXB
                thumbnail_url:
                tags: []
                price:
                  id: price_gbHJdmfrXB
                  currency: USD
                  amount: '19.99'
                  compare_at_amount:
                  price_list_id:
                  min_quantity: 1
                  variant_id: variant_gbHJdmfrXB
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                original_price:
                seller_id:
                external_references: {}
                status: active
                metadata: {}
                deleted_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                delivery_profile_id: fp_UkLWZg9DAJ
                seller_name:
                product_type_id:
                tax_category_id: taxcat_UkLWZg9DAJ
              schema:
                "$ref": "#/components/schemas/Product"
        '422':
          description: the product is not awaiting review
          content:
            application/json:
              example:
                error:
                  code: processing_error
                  message: This product is not awaiting review.
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/admin/products/{id}/reject":
    parameters:
    - name: id
      in: path
      required: true
      description: Product ID
      schema:
        type: string
    patch:
      summary: Reject a submitted product
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Turns down a product a seller submitted for review. The `reason` is
        sent back to the seller, who can fix the product and submit it again.


        **Required scope:** `write_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // The seller sees the reason, fixes the product and submits it again.
          const product = await client.products.reject('prod_86Rf07xd4z', {
            reason: 'Photos are too dark',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /products/{id}/reject -d '{"reason":"Photos are too
          dark"}'
      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: product rejected
          content:
            application/json:
              example:
                id: prod_gbHJdmfrXB
                name: Product 1564387
                slug: product-1564387
                meta_title:
                meta_description:
                meta_keywords:
                variant_count: 1
                available_on:
                preorder_ships_at:
                purchasable: true
                preorder: false
                in_stock: false
                backorderable: true
                available: false
                description: Iste blanditiis quos vero ipsam reprehenderit quae. Culpa
                  recusandae ut quisquam facilis enim dolorum eius. Sapiente explicabo
                  animi necessitatibus perspiciatis doloribus aspernatur nobis. Labore
                  similique ipsa debitis voluptate a. Nemo occaecati magnam quos voluptatibus
                  amet. Facilis quis aperiam corporis corrupti enim. Voluptate dignissimos
                  alias exercitationem repudiandae eligendi rerum hic. Facilis sed
                  doloremque dicta porro saepe. Ipsam alias et ipsum voluptatum aperiam
                  molestiae aliquam tempora. Quod ipsa quas eos hic corrupti dignissimos
                  dolorum occaecati. Commodi quis animi at possimus laborum beatae.
                  Aliquam vero suscipit reiciendis dolor placeat. Deleniti corporis
                  tempora accusamus quae nesciunt animi. Numquam occaecati sapiente
                  accusantium amet illum. Vero odio reprehenderit ipsa esse aliquid
                  autem ad.
                description_html: |-
                  Iste blanditiis quos vero ipsam reprehenderit quae. Culpa recusandae ut quisquam facilis enim dolorum eius. Sapiente explicabo animi necessitatibus perspiciatis doloribus aspernatur nobis. Labore similique ipsa debitis voluptate a.
                  Nemo occaecati magnam quos voluptatibus amet. Facilis quis aperiam corporis corrupti enim. Voluptate dignissimos alias exercitationem repudiandae eligendi rerum hic.
                  Facilis sed doloremque dicta porro saepe. Ipsam alias et ipsum voluptatum aperiam molestiae aliquam tempora. Quod ipsa quas eos hic corrupti dignissimos dolorum occaecati. Commodi quis animi at possimus laborum beatae.
                  Aliquam vero suscipit reiciendis dolor placeat. Deleniti corporis tempora accusamus quae nesciunt animi. Numquam occaecati sapiente accusantium amet illum. Vero odio reprehenderit ipsa esse aliquid autem ad.
                default_variant_id: variant_gbHJdmfrXB
                buy_box_variant_id: variant_gbHJdmfrXB
                thumbnail_url:
                tags: []
                price:
                  id: price_gbHJdmfrXB
                  currency: USD
                  amount: '19.99'
                  compare_at_amount:
                  price_list_id:
                  min_quantity: 1
                  variant_id: variant_gbHJdmfrXB
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                original_price:
                seller_id:
                external_references: {}
                status: rejected
                metadata: {}
                deleted_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                delivery_profile_id: fp_UkLWZg9DAJ
                seller_name:
                product_type_id:
                tax_category_id: taxcat_UkLWZg9DAJ
              schema:
                "$ref": "#/components/schemas/Product"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ProductRejectParams"
        required: true
  "/api/v3/admin/products/{id}/activate":
    parameters:
    - name: id
      in: path
      required: true
      description: Product ID
      schema:
        type: string
    patch:
      summary: Activate a product
      tags:
      - Products
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const product = await client.products.activate('prod_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api patch /products/{id}/activate -d '{ ... }'
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Puts one product on sale. Runs the activation workflow, so its hooks and the `product.activated` event fire, which `bulk_status_update` does not. A product awaiting review is refused: approve or reject it instead.


        **Required scope:** `write_products` (for API-key authentication).
      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: product active
          content:
            application/json:
              example:
                id: prod_gbHJdmfrXB
                name: Product 1604119
                slug: product-1604119
                meta_title:
                meta_description:
                meta_keywords:
                variant_count: 1
                available_on:
                preorder_ships_at:
                purchasable: true
                preorder: false
                in_stock: false
                backorderable: true
                available: true
                description: Tempora doloribus sit consectetur cumque omnis. Quod
                  fugit dicta ullam omnis. Hic dolorem asperiores nemo est sed nihil
                  quia deleniti. Saepe aperiam eos nulla quia porro minima officiis
                  cum. Eius dignissimos laudantium sequi incidunt. Sed nihil voluptate
                  aliquid nisi. Veritatis tenetur quos aspernatur modi perspiciatis
                  quaerat. Voluptas harum neque labore fuga reprehenderit unde quasi.
                  Omnis quam autem in ipsam aspernatur architecto alias recusandae.
                  Repudiandae ratione vel expedita corporis et pariatur rem sapiente.
                  Velit laboriosam nulla quibusdam fugit minus itaque ut repellat.
                  Incidunt est fugiat totam ipsa quod deserunt. Natus sequi numquam
                  laudantium non similique saepe ipsam quos. Ad impedit necessitatibus
                  quo nesciunt blanditiis id similique recusandae. Ut occaecati debitis
                  aliquam accusantium sed distinctio neque. Labore quos quam optio
                  aperiam dolores aspernatur vitae odio. Eius nam adipisci corrupti
                  incidunt quod sapiente tempora dicta.
                description_html: |-
                  Tempora doloribus sit consectetur cumque omnis. Quod fugit dicta ullam omnis. Hic dolorem asperiores nemo est sed nihil quia deleniti.
                  Saepe aperiam eos nulla quia porro minima officiis cum. Eius dignissimos laudantium sequi incidunt. Sed nihil voluptate aliquid nisi.
                  Veritatis tenetur quos aspernatur modi perspiciatis quaerat. Voluptas harum neque labore fuga reprehenderit unde quasi. Omnis quam autem in ipsam aspernatur architecto alias recusandae. Repudiandae ratione vel expedita corporis et pariatur rem sapiente.
                  Velit laboriosam nulla quibusdam fugit minus itaque ut repellat. Incidunt est fugiat totam ipsa quod deserunt. Natus sequi numquam laudantium non similique saepe ipsam quos. Ad impedit necessitatibus quo nesciunt blanditiis id similique recusandae.
                  Ut occaecati debitis aliquam accusantium sed distinctio neque. Labore quos quam optio aperiam dolores aspernatur vitae odio. Eius nam adipisci corrupti incidunt quod sapiente tempora dicta.
                default_variant_id: variant_gbHJdmfrXB
                buy_box_variant_id: variant_gbHJdmfrXB
                thumbnail_url:
                tags: []
                price:
                  id: price_gbHJdmfrXB
                  currency: USD
                  amount: '19.99'
                  compare_at_amount:
                  price_list_id:
                  min_quantity: 1
                  variant_id: variant_gbHJdmfrXB
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                original_price:
                seller_id:
                external_references: {}
                status: active
                metadata: {}
                deleted_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                delivery_profile_id: fp_UkLWZg9DAJ
                seller_name:
                product_type_id:
                tax_category_id: taxcat_UkLWZg9DAJ
              schema:
                "$ref": "#/components/schemas/Product"
        '422':
          description: the product is awaiting review
          content:
            application/json:
              example:
                error:
                  code: product_in_review
                  message: A product awaiting review is approved or rejected, not
                    moved to another status
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/admin/products/{id}/archive":
    parameters:
    - name: id
      in: path
      required: true
      description: Product ID
      schema:
        type: string
    patch:
      summary: Archive a product
      tags:
      - Products
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const product = await client.products.archive('prod_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api patch /products/{id}/archive -d '{ ... }'
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Takes one product off sale and archives it; activating it puts it back on sale. Runs the archive workflow, so its hooks and its event fire. A product awaiting review is refused: approve or reject it instead.


        **Required scope:** `write_products` (for API-key authentication).
      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: product archived
          content:
            application/json:
              example:
                id: prod_gbHJdmfrXB
                name: Product 1644768
                slug: product-1644768
                meta_title:
                meta_description:
                meta_keywords:
                variant_count: 1
                available_on:
                preorder_ships_at:
                purchasable: true
                preorder: false
                in_stock: false
                backorderable: true
                available: false
                description: In exercitationem nobis illo accusamus non quibusdam.
                  Minus corporis commodi magni maxime cumque beatae. Exercitationem
                  provident tempore est corrupti eius at dolor. Rerum delectus id
                  aspernatur consequuntur quod enim. Quis omnis amet inventore alias
                  minima praesentium. Quaerat reprehenderit deleniti atque inventore.
                  Nemo quas nam qui architecto eligendi vel pariatur. Veritatis accusantium
                  molestias deleniti omnis autem modi. Officiis optio quidem iste
                  nihil delectus commodi. Aperiam amet omnis eum praesentium natus
                  recusandae suscipit.
                description_html: |-
                  In exercitationem nobis illo accusamus non quibusdam. Minus corporis commodi magni maxime cumque beatae. Exercitationem provident tempore est corrupti eius at dolor. Rerum delectus id aspernatur consequuntur quod enim.
                  Quis omnis amet inventore alias minima praesentium. Quaerat reprehenderit deleniti atque inventore. Nemo quas nam qui architecto eligendi vel pariatur.
                  Veritatis accusantium molestias deleniti omnis autem modi. Officiis optio quidem iste nihil delectus commodi. Aperiam amet omnis eum praesentium natus recusandae suscipit.
                default_variant_id: variant_gbHJdmfrXB
                buy_box_variant_id: variant_gbHJdmfrXB
                thumbnail_url:
                tags: []
                price:
                  id: price_gbHJdmfrXB
                  currency: USD
                  amount: '19.99'
                  compare_at_amount:
                  price_list_id:
                  min_quantity: 1
                  variant_id: variant_gbHJdmfrXB
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                original_price:
                seller_id:
                external_references: {}
                status: archived
                metadata: {}
                deleted_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                delivery_profile_id: fp_UkLWZg9DAJ
                seller_name:
                product_type_id:
                tax_category_id: taxcat_UkLWZg9DAJ
              schema:
                "$ref": "#/components/schemas/Product"
        '422':
          description: the product is awaiting review
          content:
            application/json:
              example:
                error:
                  code: product_in_review
                  message: A product awaiting review is approved or rejected, not
                    moved to another status
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/admin/products/{id}/draft":
    parameters:
    - name: id
      in: path
      required: true
      description: Product ID
      schema:
        type: string
    patch:
      summary: Move a product back to draft
      tags:
      - Products
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const product = await client.products.draft('prod_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api patch /products/{id}/draft -d '{ ... }'
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Takes one product off sale, back to a draft. Runs the draft workflow, so its hooks and its event fire. A product awaiting review is refused: approve or reject it instead.


        **Required scope:** `write_products` (for API-key authentication).
      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: product draft
          content:
            application/json:
              example:
                id: prod_gbHJdmfrXB
                name: Product 1682527
                slug: product-1682527
                meta_title:
                meta_description:
                meta_keywords:
                variant_count: 1
                available_on:
                preorder_ships_at:
                purchasable: true
                preorder: false
                in_stock: false
                backorderable: true
                available: false
                description: Temporibus fugiat ducimus quae voluptas error. Iure repellat
                  labore aperiam harum magni. Fuga ullam possimus ad repudiandae atque.
                  Excepturi quidem est expedita molestiae delectus. Optio tempora
                  sed minus voluptatum doloremque. Laborum esse voluptate nostrum
                  nesciunt. Ipsum ducimus a dolor nostrum quis corrupti quae illum.
                  Fuga provident deleniti minima ea vel. Cupiditate architecto omnis
                  reprehenderit iusto suscipit corrupti quia cumque. Voluptatem nisi
                  dignissimos aut nostrum distinctio quo explicabo fugiat. Unde minima
                  ratione enim minus officia rerum odio reiciendis. Fugiat perferendis
                  nulla voluptates voluptatum alias. Voluptatem cumque voluptatibus
                  in sint assumenda ad neque. Inventore error consequuntur exercitationem
                  officia consequatur earum iure autem. Odit iure porro reiciendis
                  placeat. Animi minus vel asperiores maiores error tempora. Dolorum
                  esse sapiente voluptatem iste culpa suscipit. Nulla sapiente sit
                  deserunt iste totam dolores. Tempora magni eveniet natus nemo optio.
                  Aliquid quis ullam illo minus. Atque distinctio sapiente voluptatibus
                  adipisci consectetur repellendus culpa dolor. Dolor pariatur tempora
                  ab repellat unde aliquam sequi. Necessitatibus aliquid fugit molestias
                  facilis ratione.
                description_html: |-
                  Temporibus fugiat ducimus quae voluptas error. Iure repellat labore aperiam harum magni. Fuga ullam possimus ad repudiandae atque. Excepturi quidem est expedita molestiae delectus. Optio tempora sed minus voluptatum doloremque.
                  Laborum esse voluptate nostrum nesciunt. Ipsum ducimus a dolor nostrum quis corrupti quae illum. Fuga provident deleniti minima ea vel. Cupiditate architecto omnis reprehenderit iusto suscipit corrupti quia cumque. Voluptatem nisi dignissimos aut nostrum distinctio quo explicabo fugiat.
                  Unde minima ratione enim minus officia rerum odio reiciendis. Fugiat perferendis nulla voluptates voluptatum alias. Voluptatem cumque voluptatibus in sint assumenda ad neque. Inventore error consequuntur exercitationem officia consequatur earum iure autem.
                  Odit iure porro reiciendis placeat. Animi minus vel asperiores maiores error tempora. Dolorum esse sapiente voluptatem iste culpa suscipit. Nulla sapiente sit deserunt iste totam dolores.
                  Tempora magni eveniet natus nemo optio. Aliquid quis ullam illo minus. Atque distinctio sapiente voluptatibus adipisci consectetur repellendus culpa dolor. Dolor pariatur tempora ab repellat unde aliquam sequi. Necessitatibus aliquid fugit molestias facilis ratione.
                default_variant_id: variant_gbHJdmfrXB
                buy_box_variant_id: variant_gbHJdmfrXB
                thumbnail_url:
                tags: []
                price:
                  id: price_gbHJdmfrXB
                  currency: USD
                  amount: '19.99'
                  compare_at_amount:
                  price_list_id:
                  min_quantity: 1
                  variant_id: variant_gbHJdmfrXB
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                original_price:
                seller_id:
                external_references: {}
                status: draft
                metadata: {}
                deleted_at:
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                delivery_profile_id: fp_UkLWZg9DAJ
                seller_name:
                product_type_id:
                tax_category_id: taxcat_UkLWZg9DAJ
              schema:
                "$ref": "#/components/schemas/Product"
        '422':
          description: the product is awaiting review
          content:
            application/json:
              example:
                error:
                  code: product_in_review
                  message: A product awaiting review is approved or rejected, not
                    moved to another status
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v3/admin/translations":
    get:
      summary: Translation coverage for a resource type
      tags:
      - Products
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Reports how much of each record is translated into each of the store's non-default locales, plus per-locale totals. A record counts as covered for a locale only when every one of its translatable fields is filled in.

        **Required scope:** `read_products` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // How much of each product is translated into each of the store's other languages.
          const { data: coverage } = await client.translations.coverage('product', {
            search: 'espresso',
            limit: 25,
          })
      - lang: bash
        label: Spree CLI
        source: spree api get /translations -d '{"search":"espresso","limit":25}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: resource_type
        in: query
        required: true
        description: A translatable resource type, e.g. `product`, `category`, `option_type`.
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: search
        in: query
        required: false
        description: Free-text term, applied through whichever predicate the resource
          type whitelists (reported back as `search_field`).
        schema:
          type: string
      responses:
        '200':
          description: coverage found
          content:
            application/json:
              example:
                data:
                  resource_type: product
                  default_locale: en
                  locales:
                  - de
                  field_count: 5
                  search_field: name_cont
                  coverage:
                  - locale: de
                    translated: 0
                    total: 1
                    coverage: 0.0
                  records:
                  - id: prod_UkLWZg9DAJ
                    label: Espresso Machine
                    locales:
                      de: 2
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous:
                  next:
        '404':
          description: resource type is not translatable
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: record not found
  "/api/v3/admin/policies":
    get:
      summary: List policies
      tags:
      - Policies
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns the store's policy documents — terms of service, privacy
        policy, returns policy, shipping policy, and any others the merchant
        has written. Every store is created with the four standard policies,
        named but empty.

        A marketplace seller's own policies are managed by the seller and are
        not listed here.


        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: policies } = await client.policies.list()
      - lang: bash
        label: Spree CLI
        source: spree api get /policies
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: q[search]
        in: query
        required: false
        schema:
          type: string
        description: Matches any of name (partial, case-insensitive).
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      - name: fields
        in: query
        required: false
        description: Comma-separated list of fields to include. id is always included.
        schema:
          type: string
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `owner_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `owner_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `created_at`, `id`, `name`, `owner_id`, `owner_type`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: Policy
        sortable:
        - created_at
        - id
        - name
        - owner_id
        - owner_type
        - updated_at
      responses:
        '200':
          description: policies listed
          content:
            application/json:
              example:
                data:
                - id: pol_gbHJdmfrXB
                  name: Privacy Policy
                  slug: privacy-policy
                  body: ''
                  body_html: ''
                  updated_at: '2026-01-15T12:00:00.000Z'
                  created_at: '2026-01-15T12:00:00.000Z'
                - id: pol_uw2YK1rnl0
                  name: Restocking Policy
                  slug: restocking-policy
                  body: Return anything unopened within 30 days.
                  body_html: "<p>Return anything unopened within 30 days.</p>"
                  updated_at: '2026-01-15T12:00:00.000Z'
                  created_at: '2026-01-15T12:00:00.000Z'
                - id: pol_EfhxLZ9ck8
                  name: Returns Policy
                  slug: returns-policy
                  body: ''
                  body_html: ''
                  updated_at: '2026-01-15T12:00:00.000Z'
                  created_at: '2026-01-15T12:00:00.000Z'
                - id: pol_VqXmZF31wY
                  name: Shipping Policy
                  slug: shipping-policy
                  body: ''
                  body_html: ''
                  updated_at: '2026-01-15T12:00:00.000Z'
                  created_at: '2026-01-15T12:00:00.000Z'
                - id: pol_UkLWZg9DAJ
                  name: Terms of Service
                  slug: terms-of-service
                  body: ''
                  body_html: ''
                  updated_at: '2026-01-15T12:00:00.000Z'
                  created_at: '2026-01-15T12:00:00.000Z'
                meta:
                  page: 1
                  limit: 25
                  count: 5
                  pages: 1
                  from: 1
                  to: 5
                  in: 5
                  previous:
                  next:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Policy"
                  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"
    post:
      summary: Create a policy
      tags:
      - Policies
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Creates a policy. `body` accepts HTML and is sanitized before it is
        stored; the stored markup is returned as `body_html`, and `body` reads
        back as plain text.

        The slug is derived from the name when one is not given, and is what
        the storefront addresses the policy by.


        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const policy = await client.policies.create({
            name: 'Wholesale Policy',
            body: '<p>Trade orders ship within five working days.</p>',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /policies -d '{"name":"Wholesale Policy","body":"<p>Trade
          orders ship within five working days.</p>"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '201':
          description: policy created
          content:
            application/json:
              example:
                id: pol_OIJLhNcSbf
                name: Wholesale Policy
                slug: wholesale-policy
                body: Trade orders ship within five working days.
                body_html: "<p>Trade orders ship within five working days.</p>"
                updated_at: '2026-01-15T12:00:00.000Z'
                created_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/Policy"
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Name can't be blank
                  details:
                    name:
                    - code: blank
                      message: can't be blank
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PolicyCreateParams"
        required: true
  "/api/v3/admin/policies/{id}":
    parameters:
    - name: id
      in: path
      required: true
      description: Policy prefixed ID or slug
      schema:
        type: string
    get:
      summary: Get a policy
      tags:
      - Policies
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a single policy, addressed by prefixed ID or by slug.

        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // Addressable by slug as well as prefixed id.
          const policy = await client.policies.get('returns-policy')
      - lang: bash
        label: Spree CLI
        source: spree api get /policies/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: policy found
          content:
            application/json:
              example:
                id: pol_uw2YK1rnl0
                name: Restocking Policy
                slug: restocking-policy
                body: Return anything unopened within 30 days.
                body_html: "<p>Return anything unopened within 30 days.</p>"
                updated_at: '2026-01-15T12:00:00.000Z'
                created_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/Policy"
        '404':
          description: policy not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Policy not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update a policy
      tags:
      - Policies
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Updates a policy. `body` accepts HTML and is sanitized before it is stored.

        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const policy = await client.policies.update('returns-policy', {
            body: '<p>Return anything unopened within 60 days.</p>',
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /policies/{id} -d '{"body":"<p>Return anything unopened
          within 60 days.</p>"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: policy updated
          content:
            application/json:
              example:
                id: pol_uw2YK1rnl0
                name: Restocking Policy
                slug: restocking-policy
                body: Return anything unopened within 60 days.
                body_html: "<p>Return anything unopened within 60 days.</p>"
                updated_at: '2026-01-15T12:00:00.000Z'
                created_at: '2026-01-15T12:00:00.000Z'
              schema:
                "$ref": "#/components/schemas/Policy"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PolicyUpdateParams"
        required: true
    delete:
      summary: Delete a policy
      tags:
      - Policies
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Deletes a policy. The four policies a store is created with can be
        deleted like any other — they are conventions, not fixtures.


        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.policies.delete('wholesale-policy')
      - lang: bash
        label: Spree CLI
        source: spree api delete /policies/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '204':
          description: policy deleted
  "/api/v3/admin/claim_reasons":
    get:
      summary: List claim reasons
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Why a customer raised a claim — what the merchant got wrong, rather than a change of mind.

        The vocabulary is the merchant's own — seeded with a starting set and
        edited from the dashboard. Inactive rows stay for the records that
        already reference them, but are not offered on new ones.


        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: reasons } = await client.claimReasons.list()
      - lang: bash
        label: Spree CLI
        source: spree api get /claim_reasons
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      - name: sort
        in: query
        required: false
        description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
        schema:
          type: string
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: ClaimReason
        sortable:
        - active
        - created_at
        - id
        - name
        - updated_at
      responses:
        '200':
          description: claim reasons found
          content:
            application/json:
              example:
                data:
                - id: clr_UkLWZg9DAJ
                  name: Arrived damaged
                  active: true
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  can_be_deleted: true
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  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 claim reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Adds a claim reason to this store. Names are unique per store, ignoring case.

        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const reason = await client.claimReasons.create({
            name: 'Arrived damaged',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /claim_reasons -d '{"name":"Arrived damaged"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '201':
          description: claim reason created
          content:
            application/json:
              example:
                id: clr_gbHJdmfrXB
                name: A new reason
                active: true
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                can_be_deleted: true
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Name can't be blank
                  details:
                    name:
                    - code: blank
                      message: can't be blank
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReasonCreateParams"
        required: true
  "/api/v3/admin/claim_reasons/{id}":
    parameters:
    - name: id
      in: path
      required: true
      description: Claim reason ID
      schema:
        type: string
    get:
      summary: Get a claim reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a single claim reason by prefixed ID.

        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const reason = await client.claimReasons.get('clr_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /claim_reasons/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: claim reason found
          content:
            application/json:
              example:
                id: clr_UkLWZg9DAJ
                name: Arrived damaged
                active: true
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                can_be_deleted: true
        '404':
          description: claim reason not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Claim reason not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update a claim reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Renames a claim reason or retires it. Deactivating keeps it on the records
        that already carry it while removing it from the pickers.


        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const reason = await client.claimReasons.update('clr_UkLWZg9DAJ', {
            active: false,
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /claim_reasons/{id} -d '{"active":false}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: claim reason updated
          content:
            application/json:
              example:
                id: clr_UkLWZg9DAJ
                name: Arrived damaged
                active: false
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                can_be_deleted: true
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReasonUpdateParams"
        required: true
    delete:
      summary: Delete a claim reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Removes a claim reason the store no longer uses. A reason already recorded
        on a document is refused — deactivate it instead, so the history it
        explains stays readable.


        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.claimReasons.delete('clr_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /claim_reasons/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '204':
          description: claim reason deleted
  "/api/v3/admin/order_cancellation_reasons":
    get:
      summary: List order cancellation reasons
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Why an order was called off before it shipped. Staff pick one when canceling.

        The vocabulary is the merchant's own — seeded with a starting set and
        edited from the dashboard. Inactive rows stay for the records that
        already reference them, but are not offered on new ones.


        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: reasons } = await client.orderCancellationReasons.list()
      - lang: bash
        label: Spree CLI
        source: spree api get /order_cancellation_reasons
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      - name: sort
        in: query
        required: false
        description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
        schema:
          type: string
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: OrderCancellationReason
        sortable:
        - active
        - created_at
        - id
        - name
        - updated_at
      responses:
        '200':
          description: order cancellation reasons found
          content:
            application/json:
              example:
                data:
                - id: ocr_UkLWZg9DAJ
                  name: Out of stock
                  active: true
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  can_be_deleted: true
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  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 order cancellation reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Adds a order cancellation reason to this store. Names are unique per store, ignoring case.

        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const reason = await client.orderCancellationReasons.create({
            name: 'Out of stock',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /order_cancellation_reasons -d '{"name":"Out of stock"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '201':
          description: order cancellation reason created
          content:
            application/json:
              example:
                id: ocr_gbHJdmfrXB
                name: A new reason
                active: true
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                can_be_deleted: true
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Name can't be blank
                  details:
                    name:
                    - code: blank
                      message: can't be blank
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReasonCreateParams"
        required: true
  "/api/v3/admin/order_cancellation_reasons/{id}":
    parameters:
    - name: id
      in: path
      required: true
      description: Order cancellation reason ID
      schema:
        type: string
    get:
      summary: Get a order cancellation reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a single order cancellation reason by prefixed ID.

        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const reason = await client.orderCancellationReasons.get('ocr_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /order_cancellation_reasons/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: order cancellation reason found
          content:
            application/json:
              example:
                id: ocr_UkLWZg9DAJ
                name: Out of stock
                active: true
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                can_be_deleted: true
        '404':
          description: order cancellation reason not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Order cancellation reason not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update a order cancellation reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Renames a order cancellation reason or retires it. Deactivating keeps it on the records
        that already carry it while removing it from the pickers.


        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const reason = await client.orderCancellationReasons.update('ocr_UkLWZg9DAJ', {
            active: false,
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /order_cancellation_reasons/{id} -d '{"active":false}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: order cancellation reason updated
          content:
            application/json:
              example:
                id: ocr_UkLWZg9DAJ
                name: Out of stock
                active: false
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                can_be_deleted: true
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReasonUpdateParams"
        required: true
    delete:
      summary: Delete a order cancellation reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Removes a order cancellation reason the store no longer uses. A reason already recorded
        on a document is refused — deactivate it instead, so the history it
        explains stays readable.


        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.orderCancellationReasons.delete('ocr_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /order_cancellation_reasons/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '204':
          description: order cancellation reason deleted
  "/api/v3/admin/refund_reasons":
    get:
      summary: List refund reasons
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Why money went back. Some rows are seeded and looked up by name, so they refuse renaming and deletion.

        The vocabulary is the merchant's own — seeded with a starting set and
        edited from the dashboard. Inactive rows stay for the records that
        already reference them, but are not offered on new ones.


        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: reasons } = await client.refundReasons.list()
      - lang: bash
        label: Spree CLI
        source: spree api get /refund_reasons
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      - name: sort
        in: query
        required: false
        description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
        schema:
          type: string
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: RefundReason
        sortable:
        - active
        - created_at
        - id
        - name
        - updated_at
      responses:
        '200':
          description: refund reasons found
          content:
            application/json:
              example:
                data:
                - id: rr_UkLWZg9DAJ
                  name: Goodwill gesture
                  active: true
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  can_be_deleted: true
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  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 refund reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Adds a refund reason to this store. Names are unique per store, ignoring case.

        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const reason = await client.refundReasons.create({
            name: 'Goodwill gesture',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /refund_reasons -d '{"name":"Goodwill gesture"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '201':
          description: refund reason created
          content:
            application/json:
              example:
                id: rr_gbHJdmfrXB
                name: A new reason
                active: true
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                can_be_deleted: true
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Name can't be blank
                  details:
                    name:
                    - code: blank
                      message: can't be blank
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReasonCreateParams"
        required: true
  "/api/v3/admin/refund_reasons/{id}":
    parameters:
    - name: id
      in: path
      required: true
      description: Refund reason ID
      schema:
        type: string
    get:
      summary: Get a refund reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a single refund reason by prefixed ID.

        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const reason = await client.refundReasons.get('rr_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /refund_reasons/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: refund reason found
          content:
            application/json:
              example:
                id: rr_UkLWZg9DAJ
                name: Goodwill gesture
                active: true
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                can_be_deleted: true
        '404':
          description: refund reason not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Refund reason not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update a refund reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Renames a refund reason or retires it. Deactivating keeps it on the records
        that already carry it while removing it from the pickers.


        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const reason = await client.refundReasons.update('rr_UkLWZg9DAJ', {
            active: false,
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /refund_reasons/{id} -d '{"active":false}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: refund reason updated
          content:
            application/json:
              example:
                id: rr_UkLWZg9DAJ
                name: Goodwill gesture
                active: false
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                can_be_deleted: true
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReasonUpdateParams"
        required: true
    delete:
      summary: Delete a refund reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Removes a refund reason the store no longer uses. A reason already recorded
        on a document is refused — deactivate it instead, so the history it
        explains stays readable.


        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.refundReasons.delete('rr_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /refund_reasons/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '204':
          description: refund reason deleted
  "/api/v3/admin/return_reasons":
    get:
      summary: List return reasons
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Why a customer is sending items back. Shared by returns and exchanges.

        The vocabulary is the merchant's own — seeded with a starting set and
        edited from the dashboard. Inactive rows stay for the records that
        already reference them, but are not offered on new ones.


        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: reasons } = await client.returnReasons.list()
      - lang: bash
        label: Spree CLI
        source: spree api get /return_reasons
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      - name: sort
        in: query
        required: false
        description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
        schema:
          type: string
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: ReturnReason
        sortable:
        - active
        - created_at
        - id
        - name
        - updated_at
      responses:
        '200':
          description: return reasons found
          content:
            application/json:
              example:
                data:
                - id: rar_UkLWZg9DAJ
                  name: Damaged in transit
                  active: true
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  can_be_deleted: true
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  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 return reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Adds a return reason to this store. Names are unique per store, ignoring case.

        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const reason = await client.returnReasons.create({
            name: 'Damaged in transit',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /return_reasons -d '{"name":"Damaged in transit"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '201':
          description: return reason created
          content:
            application/json:
              example:
                id: rar_gbHJdmfrXB
                name: A new reason
                active: true
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                can_be_deleted: true
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Name can't be blank
                  details:
                    name:
                    - code: blank
                      message: can't be blank
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReasonCreateParams"
        required: true
  "/api/v3/admin/return_reasons/{id}":
    parameters:
    - name: id
      in: path
      required: true
      description: Return reason ID
      schema:
        type: string
    get:
      summary: Get a return reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a single return reason by prefixed ID.

        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const reason = await client.returnReasons.get('rar_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /return_reasons/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: return reason found
          content:
            application/json:
              example:
                id: rar_UkLWZg9DAJ
                name: Damaged in transit
                active: true
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                can_be_deleted: true
        '404':
          description: return reason not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Return reason not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update a return reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Renames a return reason or retires it. Deactivating keeps it on the records
        that already carry it while removing it from the pickers.


        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const reason = await client.returnReasons.update('rar_UkLWZg9DAJ', {
            active: false,
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /return_reasons/{id} -d '{"active":false}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: return reason updated
          content:
            application/json:
              example:
                id: rar_UkLWZg9DAJ
                name: Damaged in transit
                active: false
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                can_be_deleted: true
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReasonUpdateParams"
        required: true
    delete:
      summary: Delete a return reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Removes a return reason the store no longer uses. A reason already recorded
        on a document is refused — deactivate it instead, so the history it
        explains stays readable.


        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          await client.returnReasons.delete('rar_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api delete /return_reasons/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '204':
          description: return reason deleted
  "/api/v3/admin/tax_exemption_reasons":
    get:
      summary: List tax exemption reasons
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Why a business buys without tax — the reasons a merchant can record on a
        tax exemption certificate. Each has the merchant's own `name` and a `code`,
        which certificates record and the tax provider receives.

        The vocabulary is the merchant's own — seeded with a starting set and
        edited from the dashboard. A provider whose engine reads the code lists
        the codes it understands on `GET /tax_providers`. Inactive rows stay on the
        certificates that already record them, but are not offered on new ones.


        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const { data: reasons } = await client.taxExemptionReasons.list()
      - lang: bash
        label: Spree CLI
        source: spree api get /tax_exemption_reasons
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
      - name: q
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
          Filters above for the list.
      - name: sort
        in: query
        required: false
        description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
        schema:
          type: string
      x-mint:
        content: |-
          ## Filters

          Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).

          | Attribute | Kind | Predicates |
          |---|---|---|
          | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
          | `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
          | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
          | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
          | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |

          **Sort by:** `active`, `code`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
      x-spree-filters:
        table: TaxExemptionReason
        sortable:
        - active
        - code
        - created_at
        - id
        - name
        - updated_at
      responses:
        '200':
          description: tax exemption reasons found
          content:
            application/json:
              example:
                data:
                - id: txr_UkLWZg9DAJ
                  name: Reseller (wholesale)
                  code: G
                  active: true
                  metadata: {}
                  created_at: '2026-01-15T12:00:00.000Z'
                  updated_at: '2026-01-15T12:00:00.000Z'
                  can_be_deleted: true
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  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 tax exemption reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Adds a tax exemption reason to this store. Names and codes are unique per store.

        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          // `code` is what certificates record and the tax engine receives — on
          // Avalara, an entity use code such as `G` (resale).
          const reason = await client.taxExemptionReasons.create({
            name: 'Reseller (wholesale)',
            code: 'G',
          })
      - lang: bash
        label: Spree CLI
        source: spree api post /tax_exemption_reasons -d '{"name":"Reseller (wholesale)","code":"G"}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '201':
          description: tax exemption reason created
          content:
            application/json:
              example:
                id: txr_gbHJdmfrXB
                name: Federal government
                code: A
                active: true
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                can_be_deleted: true
        '422':
          description: validation error
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Name can't be blank and Code can't be blank
                  details:
                    name:
                    - code: blank
                      message: can't be blank
                      specific: false
                    code:
                    - code: blank
                      message: can't be blank
                      specific: false
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/TaxExemptionReasonCreateParams"
        required: true
  "/api/v3/admin/tax_exemption_reasons/{id}":
    parameters:
    - name: id
      in: path
      required: true
      description: Tax exemption reason ID
      schema:
        type: string
    get:
      summary: Get a tax exemption reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Returns a single tax exemption reason by prefixed ID.

        **Required scope:** `read_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const reason = await client.taxExemptionReasons.get('txr_UkLWZg9DAJ')
      - lang: bash
        label: Spree CLI
        source: spree api get /tax_exemption_reasons/{id}
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        description: Bearer token for admin authentication
        schema:
          type: string
      responses:
        '200':
          description: tax exemption reason found
          content:
            application/json:
              example:
                id: txr_UkLWZg9DAJ
                name: Reseller (wholesale)
                code: G
                active: true
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                can_be_deleted: true
        '404':
          description: tax exemption reason not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Tax exemption reason not found
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    patch:
      summary: Update a tax exemption reason
      tags:
      - Reasons
      security:
      - api_key: []
        bearer_auth: []
      description: |-
        Renames a tax exemption reason or retires it. Deactivating keeps it on the
        certificates that already record it while removing it from the pickers. The
        code can change at any time, and every certificate holding the reason sends
        the new code to the tax provider from then on.


        **Required scope:** `write_settings` (for API-key authentication).
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: |-
          import { createAdminClient } from '@spree/admin-sdk'

          const client = createAdminClient({
            baseUrl: 'https://your-store.com',
            secretKey: 'sk_xxx',
          })

          const reason = await client.taxExemptionReasons.update('txr_UkLWZg9DAJ', {
            active: false,
          })
      - lang: bash
        label: Spree CLI
        source: spree api patch /tax_exemption_reasons/{id} -d '{"active":false}'
      parameters:
      - name: x-spree-api-key
        in: header
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
       

File truncated at 1 MB.