> ## Documentation Index
> Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List option types

> The marketplace's option types (Size, Colour), which a seller builds
their product's variants from.

Read only. The option types and their values are the marketplace's; a
seller picks from them when listing. Pass `expand=option_values` for
the values a variant may take, and send the chosen option type's
`name` and value's `name` as a variant's `options`. A product type's
`option_type_ids` name the option types picking it adds.


## 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](https://spreecommerce.org/docs/api-reference/admin-api/querying.md#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.


## OpenAPI

````yaml /api-reference/seller.yaml get /api/v3/seller/option_types
openapi: 3.0.3
info:
  title: Seller API
  contact:
    name: Spree Commerce
    url: https://spreecommerce.org
    email: hello@spreecommerce.org
  description: |
    Spree Seller API v3 - the marketplace seller panel, where a seller runs
    their own shop inside someone else's marketplace.

    This is a branch of its own, not a narrowing of the Admin API. Every
    endpoint is scoped server-side to the seller the request acts as, which
    is what makes cross-seller access impossible by construction rather
    than by rule. Sellers never call the Admin API.

    ## Authentication

    Sign in at `POST /api/v3/seller/auth/login` and send the returned JWT as
    `Authorization: Bearer <token>`. The token carries a `seller_api`
    audience — a token minted for the storefront or the back office is not
    accepted here, and vice versa.

    There is deliberately **no secret API key** for this branch: a
    credential that could act as a seller without a seller signing in is
    exactly what the separate audience exists to prevent.

    ### Choosing a seller

    A user may run more than one seller. Login returns the list; send the
    chosen seller's ID in the `X-Spree-Seller-Id` header on every
    authenticated request. The store is derived from the seller — never
    sent — so no header can widen what a seller reaches. A request that
    names no seller the caller belongs to is rejected with `403`.

    ## Response Format

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

    ## Error Handling

    Errors return a consistent format:
    ```json
    {
      "error": {
        "code": "validation_error",
        "message": "Validation failed",
        "details": { "name": ["can't be blank"] }
      }
    }
    ```
  version: v3
servers:
  - url: http://{defaultHost}
    variables:
      defaultHost:
        default: localhost:3000
security: []
tags:
  - name: Authentication
    description: Seller sign-in, token refresh, logout, and invitation acceptance
  - name: Account
    description: The signed-in user, the sellers they may act for, and what they may do
  - name: Claims
  - name: Countries
    description: Country and state reference data for the panel's address forms
  - name: Delivery Methods
    description: >-
      The seller's own ways to ship, and the marketplace methods shared with
      them
  - name: Delivery Profiles
    description: >-
      The marketplace's delivery vocabulary — what kind of goods a product is,
      which decides how it ships
  - name: Delivery Zones
    description: >-
      The marketplace's destinations, for narrowing where a seller's own method
      ships
  - name: Earnings
  - name: Exchanges
  - name: Exports
  - name: Files
    description: Uploading the files a profile, a submission or an import uses
  - name: Fulfillments
  - name: Imports
  - name: Onboarding
    description: >-
      The marketplace checklist a seller completes before admission, and what
      they submit against it
  - name: Option Types
    description: >-
      The marketplace's option types and values, which a seller builds variants
      from
  - name: Orders
  - name: Package Types
  - name: Policies
    description: The seller's own legal documents, as the marketplace asks them to publish
  - name: Product Types
    description: The types a seller may list a product against, and what each adds
  - name: Products
    description: The seller's own catalog
  - name: Profile
    description: >-
      The seller's own record — presentation, contact details, addresses, and
      tax registration
  - name: Returns
  - name: Stock Locations
    description: Where the seller keeps stock, and so where their returns are sent
  - name: Tax Identifiers
  - name: Team
    description: Who runs this seller, and the invitations nobody has accepted yet
paths:
  /api/v3/seller/option_types:
    get:
      tags:
        - Option Types
      summary: List option types
      description: |
        The marketplace's option types (Size, Colour), which a seller builds
        their product's variants from.

        Read only. The option types and their values are the marketplace's; a
        seller picks from them when listing. Pass `expand=option_values` for
        the values a variant may take, and send the chosen option type's
        `name` and value's `name` as a variant's `options`. A product type's
        `option_type_ids` name the option types picking it adds.
      parameters:
        - name: X-Spree-Seller-Id
          in: header
          required: true
          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: Records per page (max 100)
          schema:
            type: integer
        - name: expand
          in: query
          required: false
          description: >-
            Comma-separated associations to include. `option_values` adds the
            values.
          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.
      responses:
        '200':
          description: option types listed
          content:
            application/json:
              example:
                data:
                  - id: opt_UkLWZg9DAJ
                    name: size
                    label: Size
                    position: 1
                    kind: dropdown
                    option_values:
                      - id: optval_UkLWZg9DAJ
                        option_type_id: opt_UkLWZg9DAJ
                        name: small
                        label: Small
                        position: 1
                        color_code: null
                        option_type_name: size
                        option_type_label: Size
                        image_url: null
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous: null
                  next: null
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OptionType'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
                required:
                  - data
                  - meta
      security:
        - bearer_auth: []
      x-codeSamples:
        - lang: javascript
          label: Spree Seller SDK
          source: |-
            import { createSellerClient } from '@spree/seller-sdk'

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

            const { data: optionTypes } = await client.optionTypes.list({
              expand: ['option_values'],
              sort: 'position',
            })
components:
  schemas:
    OptionType:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        label:
          type: string
        position:
          type: number
        kind:
          type: string
          enum:
            - dropdown
            - color_swatch
            - buttons
        custom_fields:
          type: array
          items:
            $ref: '#/components/schemas/CustomField'
        option_values:
          type: array
          items:
            $ref: '#/components/schemas/OptionValue'
      required:
        - id
        - name
        - label
        - position
        - kind
      x-typelizer: true
    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 25
        count:
          type: integer
          example: 100
          description: Total number of records
        pages:
          type: integer
          example: 4
          description: Total number of pages
        from:
          type: integer
          example: 1
          description: Index of first record on this page
        to:
          type: integer
          example: 25
          description: Index of last record on this page
        in:
          type: integer
          example: 25
          description: Number of records on this page
        previous:
          type: integer
          nullable: true
          example: null
          description: Previous page number
        next:
          type: integer
          nullable: true
          example: 2
          description: Next page number
      required:
        - page
        - limit
        - count
        - pages
        - from
        - to
        - in
    CustomField:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        field_type:
          type: string
          enum:
            - short_text
            - long_text
            - rich_text
            - number
            - boolean
            - json
        key:
          type: string
        value: {}
      required:
        - id
        - label
        - field_type
        - key
        - value
      x-typelizer: true
    OptionValue:
      type: object
      properties:
        id:
          type: string
        option_type_id:
          type: string
        name:
          type: string
        label:
          type: string
        position:
          type: number
        color_code:
          type: string
          nullable: true
        option_type_name:
          type: string
        option_type_label:
          type: string
        image_url:
          type: string
          nullable: true
        custom_fields:
          type: array
          items:
            $ref: '#/components/schemas/CustomField'
      required:
        - id
        - option_type_id
        - name
        - label
        - position
        - color_code
        - option_type_name
        - option_type_label
        - image_url
      x-typelizer: true
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for an authenticated seller session (`seller_api` audience)

````

## Related topics

- [List option types](https://spreecommerce.org/docs/api-reference/admin-api/option-types/list-option-types.md)
- [List option type custom fields](https://spreecommerce.org/docs/api-reference/admin-api/option-types/list-option-type-custom-fields.md)
- [Admin API endpoint index](https://spreecommerce.org/docs/api-reference/admin-api/endpoints.md)
- [Options](https://spreecommerce.org/docs/user/products/options.md)
- [List product types](https://spreecommerce.org/docs/api-reference/seller-api/product-types/list-product-types.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.