Spree Commerce Orders API

Orders, order items, applied gift cards, and applied store credits

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/spree-orders-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no email required.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

spree-orders-api-openapi.yml Raw ↑
openapi: 3.0.3
info:
  title: Admin Account / Address Orders 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: Orders
  description: Orders, order items, applied gift cards, and applied store credits
paths:
  /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'\n\nconst client = createAdminClient({\n  baseUrl: 'https://your-store.com',\n  secretKey: 'sk_xxx',\n})\n\nawait client.orders.giftCards.apply('or_UkLWZg9DAJ', {\n  code: 'GIFT-XXXX-YYYY',\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: gift card applied
          content:
            application/json:
              example:
                id: gc_UkLWZg9DAJ
                code: B4A00253F5765132
                status: active
                currency: USD
                amount: '10.0'
                amount_used: '10.0'
                amount_authorized: '0.0'
                amount_remaining: '0.0'
                display_amount: $10.00
                display_amount_used: $10.00
                display_amount_remaining: $0.00
                expires_at: null
                redeemed_at: null
                expired: false
                active: true
                created_at: '2026-06-12T17:24:30.324Z'
                updated_at: '2026-06-12T17:24:30.627Z'
                customer_id: null
                created_by_id: null
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - code
              properties:
                code:
                  type: string
                  description: Gift card code
                  example: GIFT-XXXX-YYYY
  /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'\n\nconst client = createAdminClient({\n  baseUrl: 'https://your-store.com',\n  secretKey: 'sk_xxx',\n})\n\nawait client.orders.giftCards.remove('or_UkLWZg9DAJ', 'gc_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: 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'\n\nconst client = createAdminClient({\n  baseUrl: 'https://your-store.com',\n  secretKey: 'sk_xxx',\n})\n\nconst { data: items } = await client.orders.items.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., 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: items found
          content:
            application/json:
              example:
                data:
                - id: li_UkLWZg9DAJ
                  variant_id: variant_gbHJdmfrXB
                  quantity: 2
                  currency: USD
                  name: Product 12496
                  slug: product-12496
                  options_text: 'Size: S'
                  price: '10.0'
                  display_price: $10.00
                  total: '20.0'
                  display_total: $20.00
                  adjustment_total: '0.0'
                  display_adjustment_total: $0.00
                  additional_tax_total: '0.0'
                  display_additional_tax_total: $0.00
                  included_tax_total: '0.0'
                  display_included_tax_total: $0.00
                  discount_total: '0.0'
                  display_discount_total: $0.00
                  pre_tax_amount: '20.0'
                  display_pre_tax_amount: $20.00
                  discounted_amount: '20.0'
                  display_discounted_amount: $20.00
                  display_compare_at_amount: $0.00
                  compare_at_amount: null
                  thumbnail_url: null
                  option_values:
                  - id: optval_UkLWZg9DAJ
                    option_type_id: opt_UkLWZg9DAJ
                    name: size-1
                    label: S
                    position: 1
                    color_code: null
                    option_type_name: foo-size-10
                    option_type_label: Size
                    image_url: null
                    metadata: {}
                    created_at: '2026-06-12T17:24:31.334Z'
                    updated_at: '2026-06-12T17:24:31.334Z'
                  digital_links: []
                  metadata: {}
                  created_at: '2026-06-12T17:24:31.626Z'
                  updated_at: '2026-06-12T17:24:31.626Z'
                  cost_price: '17.0'
                  tax_category_id: taxcat_UkLWZg9DAJ
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous: null
                  next: null
    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'\n\nconst client = createAdminClient({\n  baseUrl: 'https://your-store.com',\n  secretKey: 'sk_xxx',\n})\n\nconst item = await client.orders.items.create('or_UkLWZg9DAJ', {\n  variant_id: 'variant_k5nR8xLq',\n  quantity: 2,\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: item added
          content:
            application/json:
              example:
                id: li_gbHJdmfrXB
                variant_id: variant_VqXmZF31wY
                quantity: 3
                currency: USD
                name: Product 148513
                slug: product-148513
                options_text: 'Size: S'
                price: '19.99'
                display_price: $19.99
                total: '59.97'
                display_total: $59.97
                adjustment_total: '0.0'
                display_adjustment_total: $0.00
                additional_tax_total: '0.0'
                display_additional_tax_total: $0.00
                included_tax_total: '0.0'
                display_included_tax_total: $0.00
                discount_total: '0.0'
                display_discount_total: $0.00
                pre_tax_amount: '59.97'
                display_pre_tax_amount: $59.97
                discounted_amount: '59.97'
                display_discounted_amount: $59.97
                display_compare_at_amount: $0.00
                compare_at_amount: null
                thumbnail_url: null
                option_values:
                - id: optval_gbHJdmfrXB
                  option_type_id: opt_gbHJdmfrXB
                  name: size-3
                  label: S
                  position: 1
                  color_code: null
                  option_type_name: foo-size-12
                  option_type_label: Size
                  image_url: null
                  metadata: {}
                  created_at: '2026-06-12T17:24:32.569Z'
                  updated_at: '2026-06-12T17:24:32.569Z'
                digital_links: []
                metadata: {}
                created_at: '2026-06-12T17:24:32.598Z'
                updated_at: '2026-06-12T17:24:32.598Z'
                cost_price: '17.0'
                tax_category_id: taxcat_UkLWZg9DAJ
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - variant_id
              properties:
                variant_id:
                  type: string
                  description: Prefixed variant ID
                quantity:
                  type: integer
                  default: 1
  /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'\n\nconst client = createAdminClient({\n  baseUrl: 'https://your-store.com',\n  secretKey: 'sk_xxx',\n})\n\nconst item = await client.orders.items.get('or_UkLWZg9DAJ', 'li_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: 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
                quantity: 2
                currency: USD
                name: Product 158464
                slug: product-158464
                options_text: 'Size: S'
                price: '10.0'
                display_price: $10.00
                total: '20.0'
                display_total: $20.00
                adjustment_total: '0.0'
                display_adjustment_total: $0.00
                additional_tax_total: '0.0'
                display_additional_tax_total: $0.00
                included_tax_total: '0.0'
                display_included_tax_total: $0.00
                discount_total: '0.0'
                display_discount_total: $0.00
                pre_tax_amount: '20.0'
                display_pre_tax_amount: $20.00
                discounted_amount: '20.0'
                display_discounted_amount: $20.00
                display_compare_at_amount: $0.00
                compare_at_amount: null
                thumbnail_url: null
                option_values:
                - id: optval_UkLWZg9DAJ
                  option_type_id: opt_UkLWZg9DAJ
                  name: size-4
                  label: S
                  position: 1
                  color_code: null
                  option_type_name: foo-size-13
                  option_type_label: Size
                  image_url: null
                  metadata: {}
                  created_at: '2026-06-12T17:24:32.673Z'
                  updated_at: '2026-06-12T17:24:32.673Z'
                digital_links: []
                metadata: {}
                created_at: '2026-06-12T17:24:32.963Z'
                updated_at: '2026-06-12T17:24:32.963Z'
                cost_price: '17.0'
                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'\n\nconst client = createAdminClient({\n  baseUrl: 'https://your-store.com',\n  secretKey: 'sk_xxx',\n})\n\nconst item = await client.orders.items.update('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ', {\n  quantity: 5,\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
      - 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
                quantity: 5
                currency: USD
                name: Product 166608
                slug: product-166608
                options_text: 'Size: S'
                price: '19.99'
                display_price: $19.99
                total: '99.95'
                display_total: $99.95
                adjustment_total: '0.0'
                display_adjustment_total: $0.00
                additional_tax_total: '0.0'
                display_additional_tax_total: $0.00
                included_tax_total: '0.0'
                display_included_tax_total: $0.00
                discount_total: '0.0'
                display_discount_total: $0.00
                pre_tax_amount: '99.95'
                display_pre_tax_amount: $99.95
                discounted_amount: '99.95'
                display_discounted_amount: $99.95
                display_compare_at_amount: $0.00
                compare_at_amount: null
                thumbnail_url: null
                option_values:
                - id: optval_UkLWZg9DAJ
                  option_type_id: opt_UkLWZg9DAJ
                  name: size-5
                  label: S
                  position: 1
                  color_code: null
                  option_type_name: foo-size-14
                  option_type_label: Size
                  image_url: null
                  metadata: {}
                  created_at: '2026-06-12T17:24:33.338Z'
                  updated_at: '2026-06-12T17:24:33.338Z'
                digital_links: []
                metadata: {}
                created_at: '2026-06-12T17:24:33.640Z'
                updated_at: '2026-06-12T17:24:33.979Z'
                cost_price: '17.0'
                tax_category_id: taxcat_UkLWZg9DAJ
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                quantity:
                  type: integer
    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'\n\nconst client = createAdminClient({\n  baseUrl: 'https://your-store.com',\n  secretKey: 'sk_xxx',\n})\n\nawait client.orders.items.delete('or_UkLWZg9DAJ', 'li_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: 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'\n\nconst client = createAdminClient({\n  baseUrl: 'https://your-store.com',\n  secretKey: 'sk_xxx',\n})\n\nconst order = await client.orders.storeCredits.apply('or_UkLWZg9DAJ', {\n  amount: 25.00,\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: store credit applied
          content:
            application/json:
              example:
                id: or_UkLWZg9DAJ
                market_id: null
                channel_id: ch_UkLWZg9DAJ
                number: R641610767
                email: cristi@connelly.biz
                customer_note: null
                currency: USD
                locale: en
                total_quantity: 1
                item_total: '10.0'
                display_item_total: $10.00
                adjustment_total: '0.0'
                display_adjustment_total: $0.00
                discount_total: '0.0'
                display_discount_total: $0.00
                tax_total: '0.0'
                display_tax_total: $0.00
                included_tax_total: '0.0'
                display_included_tax_total: $0.00
                additional_tax_total: '0.0'
                display_additional_tax_total: $0.00
                total: '110.0'
                display_total: $110.00
                gift_card_total: '0.0'
                display_gift_card_total: $0.00
                amount_due: '60.0'
                display_amount_due: $60.00
                delivery_total: '100.0'
                display_delivery_total: $100.00
                fulfillment_status: null
                payment_status: null
                completed_at: null
                store_credit_total: '50.0'
                display_store_credit_total: -$50.00
                covered_by_store_credit: false
                gift_card: null
                market: null
                status: draft
                last_ip_address: null
                considered_risky: false
                confirmation_delivered: false
                store_owner_notification_delivered: null
                payment_total: '0.0'
                display_payment_total: $0.00
                metadata: {}
                canceled_at: null
                approved_at: null
                created_at: '2026-06-12T17:24:41.067Z'
                updated_at: '2026-06-12T17:24:41.127Z'
                preferred_stock_location_id: null
                tags: []
                internal_note: null
                approver_id: null
                canceler_id: null
                created_by_id: null
                customer_id: cus_UkLWZg9DAJ
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  description: Optional explicit amount; defaults to order outstanding balance
    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'\n\nconst client = createAdminClient({\n  baseUrl: 'https://your-store.com',\n  secretKey: 'sk_xxx',\n})\n\nawait client.orders.storeCredits.remove('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
      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'\n\nconst client = createAdminClient({\n  baseUrl: 'https://your-store.com',\n  secretKey: 'sk_xxx',\n})\n\nconst { data: orders, meta } = await client.orders.list({\n  status_eq: 'complete',\n  completed_at_gt: '2026-01-01',\n  sort: '-completed_at',\n  limit: 25,\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: 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[state_eq]
        in: query
        required: false
        description: Filter by state (cart, address, delivery, payment, confirm, complete, canceled)
        schema:
          type: string
      - name: q[email_cont]
        in: query
        required: false
        description: Filter by email (contains)
        schema:
          type: string
      - name: q[number_eq]
        in: query
        required: false
        description: Filter by order number
        schema:
          type: string
      - name: q[completed_at_gt]
        in: query
        required: false
        description: Filter by completed after date
        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: orders found
          content:
            application/json:
              example:
                data:
                - id: or_UkLWZg9DAJ
                  market_id: null
                  channel_id: ch_UkLWZg9DAJ
                  number: R244886130
                  email: humberto_crist@waters.com
                  customer_note: null
                  currency: USD
                  locale: en
                  total_quantity: 0
                  item_total: '0.0'
                  display_item_total: $0.00
                  adjustment_total: '0.0'
                  display_adjustment_total: $0.00
                  discount_total: '0.0'
                  display_discount_total: $0.00
                  tax_total: '0.0'
                  display_tax_total: $0.00
                  included_tax_total: '0.0'
                  display_included_tax_total: $0.00
                  additional_tax_total: '0.0'
                  display_additional_tax_total: $0.00
                  total: '0.0'
                  display_total: $0.00
                  gift_card_total: '0.0'
                  display_gift_card_total: $0.00
                  amount_due: '0.0'
                  display_amount_due: $0.00
                  delivery_total: '0.0'
                  display_delivery_total: $0.00
                  fulfillment_status: null
                  payment_status: null
                  completed_at: null
                  store_credit_total: '0.0'
                  display_store_credit_total: $0.00
                  covered_by_store_credit: false
                  gift_card: null
                  market: null
                  status: draft
                  last_ip_address: null
                  considered_risky: false
                  confirmation_delivered: false
                  store_owner_notification_delivered: null
                  payment_total: '0.0'
                  display_payment_total: $0.00
                  metadata: {}
                  canceled_at: null
                  approved_at: null
                  created_at: '2026-06-12T17:24:43.024Z'
                  updated_at: '2026-06-12T17:24:43.024Z'
                  preferred_stock_location_id: null
                  tags: []
                  internal_note: null
                  approver_id: null
                  canceler_id: null
                  created_by_id: null
                  customer_id: cus_UkLWZg9DAJ
                meta:
                  page: 1
                  limit: 25
                  count: 1
                  pages: 1
                  from: 1
                  to: 1
                  in: 1
                  previous: null
                  next: null
        '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'\n\nconst client = createAdminClient({\n  baseUrl: 'https://your-store.com',\n  secretKey: 'sk_xxx',\n})\n\n// One-shot order create: customer, items, addresses, market, channel,\n// notes, metadata, and a coupon code in a single call. Everything\n// except `email` is optional.\nconst order = await client.orders.create({\n  email: 'jane@example.com',\n  customer_id: 'cus_UkLWZg9DAJ',           // Existing customer; omit for guest orders\n  use_customer_default_address: false,     // true to copy the customer's saved addresses\n\n  currency: 'USD',\n  market_id: 'mkt_UkLWZg9DAJ',\n  channel_id: 'ch_UkLWZg9DAJ',             // Optional — defaults to the store's primary channel\n  locale: 'en-US',\n\n  // Pin the order's preferred fulfillment location. Order Routing's\n  // built-in PreferredLocation rule ranks this location first when\n  // it stocks the cart's items; if it doesn't, routing falls back\n  // to the next rule (Minimize Splits → Default Location).\n  preferred_stock_location_id: 'sloc_UkLWZg9DAJ',\n\n  customer_note: 'Please leave at the front desk.',\n  internal_note: 'VIP customer — handle with care.',\n  metadata: {\n    external_reference: 'subscription_invoice_2026_04',\n    source: 'recurring-engine',\n  },\n\n  // Items: each variant_id + quantity. Optional metadata per line.\n  items: [\n    { variant_id: 'variant_k5nR8xLq', qu

# --- truncated at 32 KB (170 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spree/refs/heads/main/openapi/spree-orders-api-openapi.yml