> ## 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 order cancellation reasons

> Why an order was called off, as the marketplace defines it.

Read-only: a seller picks one when cancelling, and the operator decides
what the list holds. Retired reasons are left out.


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


## OpenAPI

````yaml /api-reference/seller.yaml get /api/v3/seller/order_cancellation_reasons
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: 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: Onboarding
    description: >-
      The marketplace checklist a seller completes before admission, and what
      they submit against it
  - 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: Stock Locations
    description: Where the seller keeps stock, and so where their returns are sent
  - name: Team
    description: Who runs this seller, and the invitations nobody has accepted yet
  - name: Files
    description: Uploading the files a profile, a submission or an import uses
paths:
  /api/v3/seller/order_cancellation_reasons:
    get:
      tags:
        - Orders
      summary: List order cancellation reasons
      description: |
        Why an order was called off, as the marketplace defines it.

        Read-only: a seller picks one when cancelling, and the operator decides
        what the list holds. Retired reasons are left out.
      parameters:
        - name: X-Spree-Seller-Id
          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.
      responses:
        '200':
          description: reasons listed
          content:
            application/json:
              example:
                data:
                  - id: ocr_UkLWZg9DAJ
                    name: Out of stock
                    active: true
                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/Reason'
                required:
                  - data
      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: reasons } = await
            client.orderCancellationReasons.list()
components:
  schemas:
    Reason:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        active:
          type: boolean
      required:
        - id
        - name
        - active
      x-typelizer: true
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for an authenticated seller session (`seller_api` audience)

````

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