openapi: 3.0.3
info:
  title: Admin Account / Address Refunds API
  contact:
    name: Spree Commerce
    url: https://spreecommerce.org
    email: hello@spreecommerce.org
  description: "Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n  \"error\": {\n    \"code\": \"validation_error\",\n    \"message\": \"Validation failed\",\n    \"details\": { \"name\": [\"can't be blank\"] }\n  }\n}\n```\n"
  version: v3
servers:
- url: http://{defaultHost}
  variables:
    defaultHost:
      default: localhost:3000
tags:
- name: Refunds
  description: Order refunds
paths:
  /api/v3/admin/orders/{order_id}/refunds:
    get:
      summary: List refunds
      tags:
      - Refunds
      security:
      - api_key: []
        bearer_auth: []
      description: 'Returns all refunds for an order.


        **Required scope:** `read_refunds` (for API-key authentication).'
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: "import { createAdminClient } from '@spree/admin-sdk'\n\nconst client = createAdminClient({\n  baseUrl: 'https://your-store.com',\n  secretKey: 'sk_xxx',\n})\n\nconst { data: refunds } = await client.orders.refunds.list('or_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
      - name: expand
        in: query
        required: false
        description: Comma-separated associations to expand (e.g., payment, refund_reason). 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,reason,transaction_id). id is always included.
        schema:
          type: string
      responses:
        '200':
          description: refunds found
          content:
            application/json:
              example:
                data: []
                meta:
                  page: 1
                  limit: 25
                  count: 0
                  pages: 1
                  from: 0
                  to: 0
                  in: 0
                  previous: null
                  next: null
    post:
      summary: Create a refund
      tags:
      - Refunds
      security:
      - api_key: []
        bearer_auth: []
      description: 'Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway.


        **Required scope:** `write_refunds` (for API-key authentication).'
      x-codeSamples:
      - lang: javascript
        label: Spree Admin SDK
        source: "import { createAdminClient } from '@spree/admin-sdk'\n\nconst client = createAdminClient({\n  baseUrl: 'https://your-store.com',\n  secretKey: 'sk_xxx',\n})\n\nconst refund = await client.orders.refunds.create('or_UkLWZg9DAJ', {\n  payment_id: 'pay_UkLWZg9DAJ',\n  amount: 5.00,\n  refund_reason_id: 'refrsn_UkLWZg9DAJ',\n})"
      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: refund created
          content:
            application/json:
              example:
                id: re_UkLWZg9DAJ
                transaction_id: BGS-68aa088bc90d
                amount: '5.0'
                payment_id: py_UkLWZg9DAJ
                refund_reason_id: rr_UkLWZg9DAJ
                reimbursement_id: null
                metadata: {}
                created_at: '2026-06-12T17:24:40.748Z'
                updated_at: '2026-06-12T17:24:40.748Z'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - payment_id
              - amount
              properties:
                payment_id:
                  type: string
                  description: Payment ID
                amount:
                  type: number
                  example: 10.0
                refund_reason_id:
                  type: string
                  description: Refund reason ID
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-spree-api-key
      in: header
      description: Secret API key for admin access
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for admin user authentication
x-tagGroups:
- name: Authentication
  tags:
  - Authentication
- name: Products & Catalog
  tags:
  - Products
  - Variants
  - Option Types
  - Custom Fields
  - Channels
- name: Pricing
  tags:
  - Pricing
  - Markets
- name: Orders & Fulfillment
  tags:
  - Orders
  - Payments
  - Fulfillments
  - Refunds
- name: Customers
  tags:
  - Customers
  - Customer Groups
- name: Promotions & Gift Cards
  tags:
  - Promotions
  - Gift Cards
- name: Data
  tags:
  - Exports
- name: Configuration
  tags:
  - Settings
  - Stock Locations
  - Payment Methods
  - Staff
  - API Keys
  - Allowed Origins
  - Webhooks