> ## 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.

# Create a draft order

> 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).



## OpenAPI

````yaml /api-reference/admin.yaml post /api/v3/admin/orders
openapi: 3.0.3
info:
  title: Admin 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.


    ## 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
servers:
  - url: http://{defaultHost}
    variables:
      defaultHost:
        default: localhost:3000
security: []
tags:
  - name: Authentication
    description: Admin user authentication
  - name: Product Catalog
    description: Products, variants, and option types
  - name: Orders
    description: >-
      Order management — orders, items, payments, fulfillments, refunds, gift
      cards, store credits
  - name: Customers
    description: Customer management — profiles, addresses, store credits, credit cards
  - name: Configuration
    description: Store configuration — payment methods, tag autocomplete
paths:
  /api/v3/admin/orders:
    post:
      tags:
        - Orders
      summary: Create a draft order
      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
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  example: customer@example.com
                customer_id:
                  type: string
                  description: 'Customer ID. Alias: user_id (legacy).'
                use_customer_default_address:
                  type: boolean
                  description: >-
                    When true with customer_id, copies the customer's saved
                    billing/shipping addresses onto the order.
                currency:
                  type: string
                  example: USD
                market_id:
                  type: string
                  description: Market ID
                channel_id:
                  type: string
                  description: >-
                    Channel ID. Defaults to the store primary channel when
                    omitted.
                preferred_stock_location_id:
                  type: string
                  description: >-
                    Stock Location ID to prefer for fulfillment. Order Routing's
                    built-in PreferredLocation rule reads this and ranks the
                    location first; routing falls back to the next rule when the
                    preferred location can't cover the cart.
                locale:
                  type: string
                  example: en-US
                customer_note:
                  type: string
                  description: Public, customer-visible note
                internal_note:
                  type: string
                  description: Staff-only note
                metadata:
                  type: object
                  description: Arbitrary key/value metadata
                shipping_address:
                  type: object
                  properties:
                    first_name:
                      type: string
                    last_name:
                      type: string
                    address1:
                      type: string
                    city:
                      type: string
                    postal_code:
                      type: string
                    country_iso:
                      type: string
                    state_abbr:
                      type: string
                    phone:
                      type: string
                shipping_address_id:
                  type: string
                  description: Existing customer address ID
                billing_address:
                  type: object
                  properties:
                    first_name:
                      type: string
                    last_name:
                      type: string
                    address1:
                      type: string
                    city:
                      type: string
                    postal_code:
                      type: string
                    country_iso:
                      type: string
                    state_abbr:
                      type: string
                    phone:
                      type: string
                billing_address_id:
                  type: string
                  description: Existing customer address ID
                items:
                  type: array
                  items:
                    type: object
                    required:
                      - variant_id
                      - quantity
                    properties:
                      variant_id:
                        type: string
                        description: Variant ID
                      quantity:
                        type: integer
                        example: 1
                      metadata:
                        type: object
                coupon_code:
                  type: string
                  description: >-
                    Optional. Applied non-fatally; invalid codes do not block
                    creation.
      responses:
        '201':
          description: order created with preferred_stock_location_id
          content:
            application/json:
              example:
                id: or_gbHJdmfrXB
                market_id: null
                channel_id: ch_UkLWZg9DAJ
                number: R338726767
                email: pinned@example.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-05-17T22:58:04.037Z'
                updated_at: '2026-05-17T22:58:04.041Z'
                preferred_stock_location_id: sloc_UkLWZg9DAJ
                tags: []
                internal_note: null
                approver_id: null
                canceler_id: null
                created_by_id: null
                customer_id: null
      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: 'jane@example.com',
              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.',
              internal_note: 'VIP customer — handle with care.',
              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_iso: 'US',
                state_abbr: '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_iso: 'US',
                state_abbr: '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',
            })
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

````