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', quantity: 2 },\n { variant_id: 'variant_QXyZ12abCD', quantity: 1, metadata: { gift: true } },\n ],\n\n // Provide addresses inline OR by ID (existing customer addresses).\n shipping_address: {\n first_name: 'Jane',\n last_name: 'Doe',\n address1: '350 Fifth Avenue',\n address2: 'Floor 42',\n city: 'New York',\n postal_code: '10118',\n country_iso: 'US',\n state_abbr: 'NY',\n phone: '+1 212 555 1234',\n company: 'Acme Inc.',\n },\n // shipping_address_id: 'addr_UkLWZg9DAJ', // alternative to inline\n\n billing_address: {\n first_name: 'Jane',\n last_name: 'Doe',\n address1: '350 Fifth Avenue',\n city: 'New York',\n postal_code: '10118',\n country_iso: 'US',\n state_abbr: 'NY',\n phone: '+1 212 555 1234',\n },\n // billing_address_id: 'addr_UkLWZg9DAJ',\n\n // Optional. Invalid codes are non-fatal — the order is created either way.\n coupon_code: 'WELCOME10',\n})" 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 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: R886479771 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-06-12T17:24:44.884Z' updated_at: '2026-06-12T17:24:44.888Z' preferred_stock_location_id: sloc_UkLWZg9DAJ tags: [] internal_note: null approver_id: null canceler_id: null created_by_id: null customer_id: null 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. /api/v3/admin/orders/{id}: get: summary: Show an order tags: - Orders security: - api_key: [] bearer_auth: [] description: 'Returns full order details including admin-only fields. **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 order = await client.orders.get('or_UkLWZg9DAJ', {\n expand: ['items', 'fulfillments', 'payments', 'customer'],\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: id in: path required: true description: Order ID (e.g., or_xxx) 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: order found content: application/json: example: id: or_UkLWZg9DAJ market_id: null channel_id: ch_UkLWZg9DAJ number: R954821619 email: yasmin_hand@windler.co.uk 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:45.173Z' updated_at: '2026-06-12T17:24:45.173Z' preferred_stock_location_id: null tags: [] internal_note: null approver_id: null canceler_id: null created_by_id: null customer_id: cus_UkLWZg9DAJ '404': description: order not found content: application/json: example: error: code: order_not_found message: Order not found schema: $ref: '#/components/schemas/ErrorResponse' patch: summary: Update an order tags: - Orders security: - api_key: [] bearer_auth: [] description: 'Updates an order. Supports updating email, addresses, special instructions, and line items. **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 order = await client.orders.update('or_UkLWZg9DAJ', {\n email: 'updated@example.com',\n internal_note: 'VIP — gift wrap on next order',\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: id in: path required: true description: Order ID schema: type: string responses: '200': description: order updated content: application/json: example: id: or_UkLWZg9DAJ market_id: null channel_id: ch_UkLWZg9DAJ number: R935476385 email: updated@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-06-12T17:24:46.324Z' updated_at: '2026-06-12T17:24:46.625Z' 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: email: type: string special_instructions: type: string internal_note: type: string channel_id: type: string description: Channel ID preferred_stock_location_id: type: string description: Stock Location ID to prefer for fulfillment. Re-runs Order Routing's PreferredLocation rule on subsequent shipment rebuilds. ship_address: type: object properties: firstname: type: string lastname: type: string address1: type: string city: type: string zipcode: type: string country_iso: type: string state_abbr: type: string phone: type: string bill_address: type: object properties: firstname: type: string lastname: type: string address1: type: string city: type: string zipcode: type: string country_iso: type: string state_abbr: type: string phone: type: string items: type: array items: type: object required: - variant_id properties: variant_id: type: string description: Variant ID quantity: type: integer example: 1 metadata: type: object delete: summary: Delete a draft order tags: - Orders security: - api_key: [] bearer_auth: [] description: 'Deletes a draft order. Completed orders cannot be deleted. **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.delete('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: id in: path required: true description: Order ID schema: type: string responses: '204': description: order deleted /api/v3/admin/orders/{id}/complete: patch: summary: Complete an order tags: - Orders security: - api_key: [] bearer_auth: [] description: 'Completes an order in the `confirm` state, marking it as placed. Set `notify_customer: true` to send the order confirmation email. **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 order = await client.orders.complete('or_UkLWZg9DAJ', {\n notify_customer: true,\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: id in: path required: true description: Order ID schema: type: string responses: '200': description: order completed content: application/json: example: id: or_UkLWZg9DAJ market_id: null channel_id: ch_UkLWZg9DAJ number: R858666014 email: percy.nitzsche@vonrueden.us 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: '0.0' display_amount_due: $0.00 delivery_total: '100.0' display_delivery_total: $100.00 fulfillment_status: ready payment_status: paid completed_at: '2026-06-12T17:24:47.655Z' 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: '110.0' display_payment_total: $110.00 metadata: {} canceled_at: null approved_at: null created_at: '2026-06-12T17:24:47.569Z' updated_at: '2026-06-12T17:24:47.707Z' preferred_stock_location_id: null tags: [] internal_note: null approver_id: null canceler_id: null created_by_id: null customer_id: cus_UkLWZg9DAJ '422': description: order cannot be completed content: application/json: example: error: code: order_cannot_complete message: No payment found details: base: - No payment found schema: $ref: '#/components/schemas/ErrorResponse' requestBody: content: application/json: schema: type: object properties: notify_customer: type: boolean description: Send the order confirmation email after completion. /api/v3/admin/orders/{id}/cancel: patch: summary: Cancel an order tags: - Orders security: - api_key: [] bearer_auth: [] description: 'Cancels a completed 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 order = await client.orders.cancel('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: id in: path required: true description: Order ID schema: type: string responses: '200': description: order canceled content: application/json: example: id: or_UkLWZg9DAJ market_id: null channel_id: ch_UkLWZg9DAJ number: R332298067 email: floria.harris@hagenes.name 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: '20.0' display_total: $20.00 gift_card_total: '0.0' display_gift_card_total: $0.00 amount_due: '-0.0' display_amount_due: $0.00 delivery_total: '10.0' display_delivery_total: $10.00 fulfillment_status: canceled payment_status: void completed_at: '2026-06-12T17:24:49.066Z' store_credit_total: '0.0' display_store_credit_total: $0.00 covered_by_store_credit: false gift_card: null market: null status: canceled 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: '2026-06-12T17:24:49.365Z' approved_at: null created_at: '2026-06-12T17:24:49.003Z' updated_at: '2026-06-12T17:24:49.416Z' preferred_stock_location_id: null tags: [] internal_note: null approver_id: null canceler_id: admin_UkLWZg9DAJ created_by_id: null customer_id: cus_UkLWZg9DAJ /api/v3/admin/orders/{id}/approve: patch: summary: Approve an order tags: - Orders security: - api_key: [] bearer_auth: [] description: 'Approves an order (e.g., for fraud review). **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 order = await client.orders.approve('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: id in: path required: true description: Order ID schema: type: string responses: '200': description: order approved content: application/json: example: id: or_UkLWZg9DAJ market_id: null channel_id: ch_UkLWZg9DAJ number: R700530633 email: coleen_hahn@kozey.us 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: '110.0' display_amount_due: $110.00 delivery_total: '100.0' display_delivery_total: $100.00 fulfillment_status: null payment_status: null completed_at: '2026-06-12T17:24:49.783Z' 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: '2026-06-12T17:24:50.082Z' created_at: '2026-06-12T17:24:49.725Z' updated_at: '2026-06-12T17:24:49.783Z' preferred_stock_location_id: null tags: [] internal_note: null approver_id: admin_UkLWZg9DAJ canceler_id: null created_by_id: null customer_id: cus_UkLWZg9DAJ /api/v3/admin/orders/{id}/resume: patch: summary: Resume a canceled order tags: - Orders security: - api_key: [] bearer_auth: [] description: 'Resumes a previously canceled 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 order = await client.orders.resume('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: id in: path required: true description: Order ID schema: type: string responses: '200': description: order resumed content: application/json: example: id: or_UkLWZg9DAJ market_id: null channel_id: ch_UkLWZg9DAJ number: R883442430 email: cameron_hegmann@orn.ca 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: '20.0' display_total: $20.00 gift_card_total: '0.0' display_gift_card_total: $0.00 amount_due: '20.0' display_amount_due: $20.00 delivery_total: '10.0' display_delivery_total: $10.00 fulfillment_status: canceled payment_status: void completed_at: '2026-06-12T17:24:50.441Z' store_credit_total: '0.0' display_store_credit_total: $0.00 covered_by_store_credit: false gift_card: null market: null status: placed 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: '2026-06-12T17:24:50.726Z' approved_at: null created_at: '2026-06-12T17:24:50.376Z' updated_at: '2026-06-12T17:24:50.822Z' preferred_stock_location_id: null tags: [] internal_note: null approver_id: null canceler_id: admin_UkLWZg9DAJ created_by_id: null customer_id: cus_UkLWZg9DAJ /api/v3/admin/orders/{id}/resend_confirmation: post: summary: Resend confirmation email tags: - Orders security: - api_key: [] bearer_auth: [] description: 'Publishes the order.completed event to trigger confirmation email delivery. **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.resendConfirmation('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: id in: path required: true description: Order ID schema: type: string responses: '200': description: confirmation resent content: application/json: example: id: or_UkLWZg9DAJ market_id: null channel_id: ch_UkLWZg9DAJ number: R467281645 email: tyra_barton@hessel.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: '110.0' display_amount_due: $110.00 delivery_total: '100.0' display_delivery_total: $100.00 fulfillment_status: null payment_status: null completed_at: '2026-06-12T17:24:51.184Z' 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:51.117Z' updated_at: '2026-06-12T17:24:51.184Z' preferred_stock_location_id: null tags: [] internal_note: null approver_id: null canceler_id: null created_by_id: null customer_id: cus_UkLWZg9DAJ /api/v2/platform/orders: get: summary: Return a list of Orders tags: - Orders security: - bearer_auth: [] description: Returns a list of Orders operationId: orders-list parameters: - name: page in: query example: 1 schema: type: integer - name: per_page in: query example: 50 schema: type: integer - name: include in: query description: 'Select which associated resources you would like to fetch, see: https://jsonapi.org/format/#fetching-includes' example: line_items,variants,product schema: type: string - name: filter[state_eq] in: query description: '' example: complete schema: type: string responses: '200': description: Records returned content: application/vnd.api+json: examples: Example: value: data: - id: '40' type: order attributes: number: R936148131 item_total: '0.0' total: '0.0' state: cart adjustment_total: '0.0' completed_at: null payment_total: '0.0' shipment_state: null payment_state: null email: murray_harber@strosin.ca special_instructions: null created_at: '2022-11-08T19:34:36.444Z' updated_at: '2022-11-08T19:34:36.444Z' currency: USD last_ip_address: null shipment_total: '0.0' additional_tax_total: '0.0' promo_total: '0.0' channel: spree included_tax_total: '0.0' item_count: 0 approved_at: null confirmation_delivered: false canceled_at: null state_lock_version: 0 taxable_adjustment_total: '0.0' non_taxable_adjustment_total: '0.0' store_owner_notification_delivered: null public_metadata: {} private_metadata: {} internal_note: null display_ship_total: $0.00 display_shipment_total: $0.00 display_outstanding_balance: $0.00 display_item_total: $0.00 display_adjustment_total: $0.00 display_included_tax_total: $0.00 display_additional_tax_total: $0.00 display_tax_total: $0.00 display_promo_total: $0.00 display_total: $0.00 display_cart_promo_total: $0.00 display_pre_tax_item_amount: $0.00 display_pre_tax_total: $0.00 display_total_applicable_store_credit: $0.00 display_total_applied_store_credit: $0.00 display_order_total_after_store_credit: $0.00 display_total_available_store_credit: $0.00 display_store_credit_remaining_after_capture: $0.00 relationships: user: data: id: '41' type: user created_by: data: null approver: data: null canceler: data: null bill_address: data: id: '52' type: address ship_address: data: null line_items: data: [] payments: data: [] shipments: data: [] state_changes: data: [] return_authorizations: data: [] reimbursements: data: [] adjustments: data: [] all_adjustments: data: [] order_promotions: data: [] - id: '41' type: order attributes: number: R877925031 item_total: '0.0' total: '0.0' state: cart adjustment_total: '0.0' completed_at: null payment_total: '0.0' shipment_state: null payment_state: null email: bronwyn@legroscorkery.ca special_instructions: null created_at: '2022-11-08T19:34:36.455Z' updated_at: '2022-11-08T19:34:36.455Z' currency: USD last_ip_address: null shipment_total: '0.0' additional_tax_total: '0.0' promo_total: '0.0' channel: spree included_tax_total: '0.0' item_count: 0 approved_at: null confirmation_delivered: false canceled_at: null state_lock_version: 0 taxable_adjustment_total: '0.0' non_taxable_adjustment_total: '0.0' store_owner_notification_delivered: null public_metadata: {} private_metadata: {} internal_note: null display_ship_total: $0.00 display_shipment_total: $0.00 display_outstanding_balance: $0.00 display_item_total: $0.00 display_adjustment_total: $0.00 display_included_tax_total: $0.00 display_additional_tax_total: $0.00 display_tax_total: $0.00 display_promo_total: $0.00 display_total: $0.00 display_cart_promo_total: $0.00 display_pre_tax_item_amount: $0.00 display_pre_tax_total: $0.00 display_total_applicable_store_credit: $0.00 display_total_applied_store_credit: $0.00 display_order_total_after_store_credit: $0.00 display_total_available_store_credit: $0.00 display_store_credit_remaining_after_capture: $0.00 relationships: user: data: id: '42' type: user created_by: data: null approver: data: null canceler: data: null bill_address: data: id: '53' type: address ship_address: data: null line_items: data: [] payments: data: [] shipments: data: [] state_changes: data: [] return_authorizations: data: [] reimbursements: data: [] adjustments: data: [] all_adjustments: data: [] order_promotions: data: [] meta: count: 2 total_count: 2 total_pages: 1 links: self: http://www.example.com/api/v2/platform/orders?page=1&per_page=&include=&filter[state_eq]= next: http://www.example.com/api/v2/platform/orders?filter%5Bstate_eq%5D=&include=&page=1&per_page= prev: http://www.example.com/api/v2/platform/orders?filter%5Bstate_eq%5D=&include=&page=1&per_page= last: http://www.example.com/api/v2/platform/orders?filter%5Bstate_eq%5D=&include=&page=1&per_page= first: http://www.example.com/api/v2/platform/orders?filter%5Bstate_eq%5D=&include=&page=1&per_page= schema: $ref: '#/components/schemas/resources_list' '401': description: Authentication Failed content: application/vnd.api+json: examples: Example: value: error: The access token is invalid schema: $ref: '#/components/schemas/error' post: summary: Creates an Order tags: - Orders security: - bearer_auth: [] description: Creates an Order operationId: create-order parameters: - name: include in: query description: 'Select which associated resources you would like to fetch, see: https://jsonapi.org/format/#fetching-includes' example: line_items,variants,product schema: type: string responses: '201': description: Record created content: application/vnd.api+json: examples: Example: value: data: id: '44' type: order attributes: number: R304058941 item_total: '0.0' total: '0.0' state: cart adjustment_total: '0.0' completed_at: null payment_total: '0.0' shipment_state: null payment_state: null email: null special_instructions: null created_at: '2022-11-08T19:34:37.269Z' updated_at: '2022-11-08T19:34:37.289Z' currency: USD last_ip_address: null shipment_total: '0.0' additional_tax_total: '0.0' promo_total: '0.0' channel: spree included_tax_total: '0.0' item_count: 0 approved_at: null confirmation_delivered: false canceled_at: null state_lock_version: 0 taxable_adjustment_total: '0.0' non_taxable_adjustment_total: '0.0' store_owner_notification_delivered: null public_metadata: {} private_metadata: {} internal_note: null display_ship_total: $0.00 display_shipment_total: $0.00 display_outstanding_balance: $0.00 display_item_total: $0.00 display_adjustment_total: $0.00 display_included_tax_total: $0.00 display_additional_tax_total: $0.00 display_tax_total: $0.00 display_promo_total: $0.00 display_total: $0.00 display_cart_promo_total: $0.00 display_pre_tax_item_amount: $20.00 display_pre_tax_total: $20.00 display_total_applicable_store_credit: $0.00 display_total_applied_store_credit: $0.00 display_order_total_after_store_credit: $0.00 display_total_available_store_credit: $0.00 display_store_credit_remaining_after_capture: $0.00 relationships: user: data: null created_by: data: null approver: data: null canceler: data: null bill_address: data: id: '56' type: address ship_address: data: id: '56' type: address line_items: data: - id: '35' type: line_item payments: data: - id: '1' type: payment shipments: data: [] state_changes: data: [] return_authorizations: data: [] reimbursements: data: [] adjustments: data: [] all_adjustments: data: [] order_promotions: data: [] schema: $ref: '#/components/schemas/resource' requestBody: content: application/json: schema: $ref: '#/components/schemas/create_order_params' /api/v2/platform/orders/{id}: get: summary: Return an Order tags: - Orders security: - bearer_auth: [] description: Returns an Order operationId: show-order parameters: - name: id in: path required: true schema: type: string - name: include in: query description: 'Select which associated resources you would like to fetch, see: https://jsonapi.org/format/#fetching-includes' example: line_items,variants,product schema: type: string responses: '200': description: Record found content: application/vnd.api+json: examples: Example: value: data: id: '45' type: order attributes: number: R612921489 item_total: '10.0' total: '110.0' state: delivery adjustment_total: '0.0' completed_at: null payment_total: '0.0' shipment_state: null payment_state: null email: salome_rowe@lehner.com special_instructions: null created_at: '2022-11-08T19:34:37.360Z' updated_at: '2022-11-08T19:34:37.513Z' currency: USD last_ip_address: null shipment_total: '100.0' additional_tax_total: '0.0' promo_total: '0.0' channel: spree included_tax_total: '0.0' item_count: 1 approved_at: null confirmation_delivered: false canceled_at: null state_lock_version: 0 taxable_adjustment_total: '0.0' non_taxable_adjustment_total: '0.0' store_owner_notification_delivered: null public_metadata: {} private_metadata: {} internal_note: null display_ship_total: $100.00 display_shipment_total: $100.00 display_outstanding_balance: $110.00 display_item_total: $10.00 display_adjustment_total: $0.00 display_included_tax_total: $0.00 display_additional_tax_total: $0.00 display_tax_total: $0.00 display_promo_total: $0.00 display_total: $110.00 display_cart_promo_total: $0.00 display_pre_tax_item_amount: $10.00 display_pre_tax_total: $10.00 display_total_applicable_store_credit: $0.00 display_total_applied_store_credit: $0.00 display_order_total_after_store_credit: $110.00 display_total_available_store_credit: $0.00 display_store_credit_remaining_after_capture: $0.00 relationships: user: data: id: '45' type: user created_by: data: null approver: data: null canceler: data: null bill_address: data: id: '57' type: address ship_address: data: id: '58' type: address line_items: data: - id: '36' type: line_item payments: data: [] shipments: data: - id: '1' type: shipment state_changes: data: [] return_authorizations: data: [] reimbursements: data: [] adjustments: data: [] all_adjustments: data: [] order_promotions: data: [] schema: $ref: '#/components/schemas/resource' '404': description: Record not found content: application/vnd.api+json: examples: Example: value: error: The resource you were looking for could not be found. schema: $ref: '#/components/schemas/error' '401': description: Authentication Failed content: application/vnd.api+json: examples: Example: value: error: The access token is invalid schema: $ref: '#/components/schemas/error' patch: summary: Update an Order tags: - Orders security: - bearer_auth: [] description: Updates an Order operationId: update-order parameters: - name: id in: path required: true schema: type: string - name: include in: query description: 'Select which associated resources you would like to fetch, see: https://jsonapi.org/format/#fetching-includes' example: line_items,variants,product schema: type: string responses: '200': description: Record updated content: application/vnd.api+json: examples: Example: value: data: id: '47' type: order attributes: number: R484277352 item_total: '10.0' total: '110.0' state: delivery adjustment_total: '0.0' completed_at: null payment_total: '0.0' shipment_state: null payment_state: null email: new@example.com special_instructions: null created_at: '2022-11-08T19:34:38.200Z' updated_at: '2022-11-08T19:34:38.599Z' currency: USD last_ip_address: null shipment_total: '100.0' additional_tax_total: '0.0' promo_total: '0.0' channel: spree included_tax_total: '0.0' item_count: 1 approved_at: null confirmation_delivered: false canceled_at: null state_lock_version: 0 taxable_adjustment_total: '0.0' non_taxable_adjustment_total: '0.0' store_owner_notification_delivered: null public_metadata: {} private_metadata: {} internal_note: null display_ship_total: $100.00 display_shipment_total: $100.00 display_outstanding_balance: $110.00 display_item_total: $10.00 display_adjustment_total: $0.00 display_included_tax_total: $0.00 display_additional_tax_total: $0.00 display_tax_total: $0.00 display_promo_total: $0.00 display_total: $110.00 display_cart_promo_total: $0.00 display_pre_tax_item_amount: $10.00 display_pre_tax_total: $10.00 display_total_applicable_store_credit: $0.00 display_total_applied_store_credit: $0.00 display_order_total_after_store_credit: $110.00 display_total_available_store_credit: $0.00 display_store_credit_remaining_after_capture: $0.00 relationships: user: data: id: '47' type: user created_by: data: null approver: data: null canceler: data: null bill_address: data: id: '61' type: address ship_address: data: id: '62' type: address line_items: data: - id: '38' type: line_item payments: data: [] shipments: data: - id: '3' type: shipment state_changes: data: [] return_authorizations: data: [] reimbursements: data: [] adjustments: data: [] all_adjustments: data: [] order_promotions: data: [] schema: $ref: '#/components/schemas/resource' '422': description: Invalid request content: application/vnd.api+json: examples: Example: value: error: Email is invalid errors: email: - is invalid schema: $ref: '#/components/schemas/validation_errors' '404': description: Record not found content: application/vnd.api+json: examples: Example: value: error: The resource you were looking for could not be found. schema: $ref: '#/components/schemas/error' '401': description: Authentication Failed content: application/vnd.api+json: examples: Example: value: error: The access token is invalid schema: $ref: '#/components/schemas/error' requestBody: content: application/json: schema: $ref: '#/components/schemas/update_order_params' delete: summary: Delete an Order tags: - Orders security: - bearer_auth: [] description: Deletes an Order operationId: delete-order parameters: - name: id in: path required: true schema: type: string responses: '204': description: Record deleted '404': description: Record not found content: application/vnd.api+json: examples: Example: value: error: The resource you were looking for could not be found. schema: $ref: '#/components/schemas/error' '401': description: Authentication Failed content: application/vnd.api+json: examples: Example: value: error: The access token is invalid schema: $ref: '#/components/schemas/error' /api/v2/platform/orders/{id}/advance: patch: summary: Advances an Order tags: - Orders security: - bearer_auth: [] description: Advances an Order operationId: advance-order parameters: - name: id in: path required: true schema: type: string - name: include in: query description: 'Select which associated resources you would like to fetch, see: https://jsonapi.org/format/#fetching-includes' example: line_items,variants,product schema: type: string responses: '200': description: Record updated content: application/vnd.api+json: examples: Example: value: data: id: '52' type: order attributes: number: R366890627 item_total: '10.0' total: '110.0' state: payment adjustment_total: '0.0' completed_at: null payment_total: '0.0' shipment_state: null payment_state: null email: sixta.larkin@bradtke.co.uk special_instructions: null created_at: '2022-11-08T19:34:40.155Z' updated_at: '2022-11-08T19:34:40.513Z' currency: USD last_ip_address: null shipment_total: '100.0' additional_tax_total: '0.0' promo_total: '0.0' channel: spree included_tax_total: '0.0' item_count: 1 approved_at: null confirmation_delivered: false canceled_at: null state_lock_version: 0 taxable_adjustment_total: '0.0' non_taxable_adjustment_total: '0.0' store_owner_notification_delivered: null public_metadata: {} private_metadata: {} internal_note: null display_ship_total: $100.00 display_shipment_total: $100.00 display_outstanding_balance: $110.00 display_item_total: $10.00 display_adjustment_total: $0.00 display_included_tax_total: $0.00 display_additional_tax_total: $0.00 display_tax_total: $0.00 display_promo_total: $0.00 display_total: $110.00 display_cart_promo_total: $0.00 display_pre_tax_item_amount: $10.00 display_pre_tax_total: $110.00 display_total_applicable_store_credit: $0.00 display_total_applied_store_credit: $0.00 display_order_total_after_store_credit: $110.00 display_total_available_store_credit: $0.00 display_store_credit_remaining_after_capture: $0.00 relationships: user: data: id: '52' type: user created_by: data: null approver: data: null canceler: data: null bill_address: data: id: '71' type: address ship_address: data: id: '72' type: address line_items: data: - id: '43' type: line_item payments: data: [] shipments: data: - id: '8' type: shipment state_changes: data: - id: '2' type: state_change return_authorizations: data: [] reimbursements: data: [] adjustments: data: [] all_adjustments: data: [] order_promotions: data: [] schema: $ref: '#/components/schemas/resource' '404': description: Record not found content: application/vnd.api+json: examples: Example: value: error: The resource you were looking for could not be found. schema: $ref: '#/components/schemas/error' '401': description: Authentication Failed content: application/vnd.api+json: examples: Example: value: error: The access token is invalid schema: $ref: '#/components/schemas/error' /api/v2/platform/orders/{id}/next: patch: summary: Next an Order tags: - Orders security: - bearer_auth: [] description: Moves an Order to the next state operationId: next-order parameters: - name: id in: path required: true schema: type: string - name: include in: query description: 'Select which associated resources you would like to fetch, see: https://jsonapi.org/format/#fetching-includes' example: line_items,variants,product schema: type: string responses: '200': description: Record updated content: application/vnd.api+json: examples: Example: value: data: id: '54' type: order attributes: number: R268996702 item_total: '10.0' total: '110.0' state: payment adjustment_total: '0.0' completed_at: null payment_total: '0.0' shipment_state: null payment_state: null email: deon.sporer@haagortiz.com special_instructions: null created_at: '2022-11-08T19:34:40.971Z' updated_at: '2022-11-08T19:34:41.324Z' currency: USD last_ip_address: null shipment_total: '100.0' additional_tax_total: '0.0' promo_total: '0.0' channel: spree included_tax_total: '0.0' item_count: 1 approved_at: null confirmation_delivered: false canceled_at: null state_lock_version: 0 taxable_adjustment_total: '0.0' non_taxable_adjustment_total: '0.0' store_owner_notification_delivered: null public_metadata: {} private_metadata: {} internal_note: null display_ship_total: $100.00 display_shipment_total: $100.00 display_outstanding_balance: $110.00 display_item_total: $10.00 display_adjustment_total: $0.00 display_included_tax_total: $0.00 display_additional_tax_total: $0.00 display_tax_total: $0.00 display_promo_total: $0.00 display_total: $110.00 display_cart_promo_total: $0.00 display_pre_tax_item_amount: $10.00 display_pre_tax_total: $110.00 display_total_applicable_store_credit: $0.00 display_total_applied_store_credit: $0.00 display_order_total_after_store_credit: $110.00 display_total_available_store_credit: $0.00 display_store_credit_remaining_after_capture: $0.00 relationships: user: data: id: '54' type: user created_by: data: null approver: data: null canceler: data: null bill_address: data: id: '75' type: address ship_address: data: id: '76' type: address line_items: data: - id: '45' type: line_item payments: data: [] shipments: data: - id: '10' type: shipment state_changes: data: - id: '3' type: state_change return_authorizations: data: [] reimbursements: data: [] adjustments: data: [] all_adjustments: data: [] order_promotions: data: [] schema: $ref: '#/components/schemas/resource' '404': description: Record not found content: application/vnd.api+json: examples: Example: value: error: The resource you were looking for could not be found. schema: $ref: '#/components/schemas/error' '401': description: Authentication Failed content: application/vnd.api+json: examples: Example: value: error: The access token is invalid schema: $ref: '#/components/schemas/error' /api/v2/platform/orders/{id}/complete: patch: summary: Completes an Order tags: - Orders security: - bearer_auth: [] description: Marks an Order as completed operationId: complete-order parameters: - name: id in: path required: true schema: type: string - name: include in: query description: 'Select which associated resources you would like to fetch, see: https://jsonapi.org/format/#fetching-includes' example: line_items,variants,product schema: type: string responses: '200': description: Record updated content: application/vnd.api+json: examples: Example: value: data: id: '56' type: order attributes: number: R923002122 item_total: '10.0' total: '110.0' state: complete adjustment_total: '0.0' completed_at: '2022-11-08T19:34:42.207Z' payment_total: '0.0' shipment_state: pending payment_state: balance_due email: adeline@hodkiewicz.co.uk special_instructions: null created_at: '2022-11-08T19:34:41.758Z' updated_at: '2022-11-08T19:34:42.207Z' currency: USD last_ip_address: null shipment_total: '100.0' additional_tax_total: '0.0' promo_total: '0.0' channel: spree included_tax_total: '0.0' item_count: 1 approved_at: null confirmation_delivered: false canceled_at: null state_lock_version: 0 taxable_adjustment_total: '0.0' non_taxable_adjustment_total: '0.0' store_owner_notification_delivered: null public_metadata: {} private_metadata: {} internal_note: null display_ship_total: $100.00 display_shipment_total: $100.00 display_outstanding_balance: $110.00 display_item_total: $10.00 display_adjustment_total: $0.00 display_included_tax_total: $0.00 display_additional_tax_total: $0.00 display_tax_total: $0.00 display_promo_total: $0.00 display_total: $110.00 display_cart_promo_total: $0.00 display_pre_tax_item_amount: $10.00 display_pre_tax_total: $110.00 display_total_applicable_store_credit: $0.00 display_total_applied_store_credit: $0.00 display_order_total_after_store_credit: $110.00 display_total_available_store_credit: $0.00 display_store_credit_remaining_after_capture: $0.00 relationships: user: data: id: '56' type: user created_by: data: null approver: data: null canceler: data: null bill_address: data: id: '79' type: address ship_address: data: id: '80' type: address line_items: data: - id: '47' type: line_item payments: data: - id: '2' type: payment shipments: data: - id: '12' type: shipment state_changes: data: - id: '4' type: state_change - id: '5' type: state_change - id: '8' type: state_change - id: '9' type: state_change - id: '10' type: state_change return_authorizations: data: [] reimbursements: data: [] adjustments: data: [] all_adjustments: data: [] order_promotions: data: [] schema: $ref: '#/components/schemas/resource' '404': description: Record not found content: application/vnd.api+json: examples: Example: value: error: The resource you were looking for could not be found. schema: $ref: '#/components/schemas/error' '401': description: Authentication Failed content: application/vnd.api+json: examples: Example: value: error: The access token is invalid schema: $ref: '#/components/schemas/error' /api/v2/platform/orders/{id}/empty: patch: summary: Empties an Order tags: - Orders security: - bearer_auth: [] description: Removes all line items, promotions, shipment and payments from an Order operationId: empty-order parameters: - name: id in: path required: true schema: type: string - name: include in: query description: 'Select which associated resources you would like to fetch, see: https://jsonapi.org/format/#fetching-includes' example: line_items,variants,product schema: type: string responses: '200': description: Record updated content: application/vnd.api+json: examples: Example: value: data: id: '59' type: order attributes: number: R688998321 item_total: '0.0' total: '0.0' state: cart adjustment_total: '0.0' completed_at: null payment_total: '0.0' shipment_state: null payment_state: null email: porsha.shanahan@nicolaszboncak.us special_instructions: null created_at: '2022-11-08T19:34:42.795Z' updated_at: '2022-11-08T19:34:43.122Z' currency: USD last_ip_address: null shipment_total: '0.0' additional_tax_total: '0.0' promo_total: '0.0' channel: spree included_tax_total: '0.0' item_count: 0 approved_at: null confirmation_delivered: false canceled_at: null state_lock_version: 0 taxable_adjustment_total: '0.0' non_taxable_adjustment_total: '0.0' store_owner_notification_delivered: null public_metadata: {} private_metadata: {} internal_note: null display_ship_total: $0.00 display_shipment_total: $0.00 display_outstanding_balance: $0.00 display_item_total: $0.00 display_adjustment_total: $0.00 display_included_tax_total: $0.00 display_additional_tax_total: $0.00 display_tax_total: $0.00 display_promo_total: $0.00 display_total: $0.00 display_cart_promo_total: $0.00 display_pre_tax_item_amount: $0.00 display_pre_tax_total: $0.00 display_total_applicable_store_credit: $0.00 display_total_applied_store_credit: $0.00 display_order_total_after_store_credit: $0.00 display_total_available_store_credit: $0.00 display_store_credit_remaining_after_capture: $0.00 relationships: user: data: id: '59' type: user created_by: data: null approver: data: null canceler: data: null bill_address: data: id: '85' type: address ship_address: data: id: '86' type: address line_items: data: [] payments: data: [] shipments: data: [] state_changes: data: [] return_authorizations: data: [] reimbursements: data: [] adjustments: data: [] all_adjustments: data: [] order_promotions: data: [] schema: $ref: '#/components/schemas/resource' '404': description: Record not found content: application/vnd.api+json: examples: Example: value: error: The resource you were looking for could not be found. schema: $ref: '#/components/schemas/error' '401': description: Authentication Failed content: application/vnd.api+json: examples: Example: value: error: The access token is invalid schema: $ref: '#/components/schemas/error' /api/v2/platform/orders/{id}/approve: patch: summary: Approves an Order tags: - Orders security: - bearer_auth: [] description: Approves an Order, when using a token created for a user, it will save this user as the approver operationId: approve-order parameters: - name: id in: path required: true schema: type: string - name: include in: query description: 'Select which associated resources you would like to fetch, see: https://jsonapi.org/format/#fetching-includes' example: line_items,variants,product schema: type: string responses: '200': description: Record approved content: application/vnd.api+json: examples: Example: value: data: id: '61' type: order attributes: number: R057732263 item_total: '10.0' total: '110.0' state: delivery adjustment_total: '0.0' completed_at: null payment_total: '0.0' shipment_state: null payment_state: null email: horacio_purdy@schroederweimann.com special_instructions: null created_at: '2022-11-08T19:34:43.561Z' updated_at: '2022-11-08T19:34:43.641Z' currency: USD last_ip_address: null shipment_total: '100.0' additional_tax_total: '0.0' promo_total: '0.0' channel: spree included_tax_total: '0.0' item_count: 1 approved_at: null confirmation_delivered: false canceled_at: null state_lock_version: 0 taxable_adjustment_total: '0.0' non_taxable_adjustment_total: '0.0' store_owner_notification_delivered: null public_metadata: {} private_metadata: {} internal_note: null display_ship_total: $100.00 display_shipment_total: $100.00 display_outstanding_balance: $110.00 display_item_total: $10.00 display_adjustment_total: $0.00 display_included_tax_total: $0.00 display_additional_tax_total: $0.00 display_tax_total: $0.00 display_promo_total: $0.00 display_total: $110.00 display_cart_promo_total: $0.00 display_pre_tax_item_amount: $10.00 display_pre_tax_total: $10.00 display_total_applicable_store_credit: $0.00 display_total_applied_store_credit: $0.00 display_order_total_after_store_credit: $110.00 display_total_available_store_credit: $0.00 display_store_credit_remaining_after_capture: $0.00 relationships: user: data: id: '61' type: user created_by: data: null approver: data: null canceler: data: null bill_address: data: id: '89' type: address ship_address: data: id: '90' type: address line_items: data: - id: '52' type: line_item payments: data: [] shipments: data: - id: '17' type: shipment state_changes: data: [] return_authorizations: data: [] reimbursements: data: [] adjustments: data: [] all_adjustments: data: [] order_promotions: data: [] schema: $ref: '#/components/schemas/resource' '404': description: Record not found content: application/vnd.api+json: examples: Example: value: error: The resource you were looking for could not be found. schema: $ref: '#/components/schemas/error' '401': description: Authentication Failed content: application/vnd.api+json: examples: Example: value: error: The access token is invalid schema: $ref: '#/components/schemas/error' /api/v2/platform/orders/{id}/cancel: patch: summary: Cancels an Order tags: - Orders security: - bearer_auth: [] description: Cancels an Order, when using a token created for a user, it will save this user as the canceler operationId: cancel-order parameters: - name: id in: path required: true schema: type: string - name: include in: query description: 'Select which associated resources you would like to fetch, see: https://jsonapi.org/format/#fetching-includes' example: line_items,variants,product schema: type: string responses: '200': description: record canceled '422': description: cannot be canceled '404': description: Record not found content: application/vnd.api+json: examples: Example: value: error: The resource you were looking for could not be found. schema: $ref: '#/components/schemas/error' '401': description: Authentication Failed content: application/vnd.api+json: examples: Example: value: error: The access token is invalid schema: $ref: '#/components/schemas/error' /api/v2/platform/orders/{id}/use_store_credit: patch: summary: Use Store Credit for an Order tags: - Orders security: - bearer_auth: [] description: Creates Store Credit payment for an Order operationId: use-store-credit-order parameters: - name: id in: path required: true schema: type: string - name: include in: query description: 'Select which associated resources you would like to fetch, see: https://jsonapi.org/format/#fetching-includes' example: line_items,variants,product schema: type: string responses: '200': description: store credit payment created '422': description: user does not have store credit available '404': description: Record not found content: application/vnd.api+json: examples: Example: value: error: The resource you were looking for could not be found. schema: $ref: '#/components/schemas/error' '401': description: Authentication Failed content: application/vnd.api+json: examples: Example: value: error: The access token is invalid schema: $ref: '#/components/schemas/error' requestBody: content: application/json: schema: $ref: '#/components/schemas/amount_param' /api/v2/platform/orders/{id}/apply_coupon_code: patch: summary: Apply Coupon Code for an Order tags: - Orders security: - bearer_auth: [] description: Creates Store Credit payment for an Order operationId: apply-coupon-code-order parameters: - name: id in: path required: true schema: type: string - name: include in: query description: 'Select which associated resources you would like to fetch, see: https://jsonapi.org/format/#fetching-includes' example: line_items,variants,product schema: type: string responses: '200': description: coupon code applied '422': description: coupon code couldn't be applied '404': description: Record not found content: application/vnd.api+json: examples: Example: value: error: The resource you were looking for could not be found. schema: $ref: '#/components/schemas/error' '401': description: Authentication Failed content: application/vnd.api+json: examples: Example: value: error: The access token is invalid schema: $ref: '#/components/schemas/error' requestBody: content: application/json: schema: $ref: '#/components/schemas/coupon_code_param' /api/v3/store/orders/{id}: get: summary: Get an order tags: - Orders security: - api_key: [] bearer_auth: [] description: Returns a single completed order by prefixed ID. Accessible via JWT (authenticated users) or order token header (guests). x-codeSamples: - lang: javascript label: Spree SDK source: "import { createClient } from '@spree/sdk'\n\nconst client = createClient({\n baseUrl: 'https://your-store.com',\n publishableKey: '',\n})\n\nconst order = await client.orders.get('or_abc123', {}, {\n token: '',\n})" parameters: - name: x-spree-api-key in: header required: true schema: type: string - name: Authorization in: header required: false description: Bearer token for authenticated customers schema: type: string - name: id in: path required: true description: Order prefixed ID schema: type: string - name: x-spree-token in: header required: false description: Order token for guest access schema: type: string - name: expand in: query required: false description: Comma-separated associations to expand (items, fulfillments, payments, discounts, billing_address, shipping_address, gift_card). Use "none" to skip associations. schema: type: string - name: fields in: query required: false description: Comma-separated list of fields to include (e.g., total,amount_due,item_count). id is always included. schema: type: string responses: '200': description: order found (guest via order token) content: application/json: example: id: or_UkLWZg9DAJ market_id: null channel_id: ch_UkLWZg9DAJ number: R528526445 email: guest@example.com 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: '110.0' display_amount_due: $110.00 delivery_total: '100.0' display_delivery_total: $100.00 fulfillment_status: null payment_status: null completed_at: '2026-05-26T16:14:12.058Z' store_credit_total: '0.0' display_store_credit_total: $0.00 covered_by_store_credit: false discounts: [] items: - id: li_UkLWZg9DAJ variant_id: variant_UkLWZg9DAJ quantity: 1 currency: USD name: Product 1325879 slug: product-1325879 options_text: '' price: '10.0' display_price: $10.00 total: '10.0' display_total: $10.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: '10.0' display_pre_tax_amount: $10.00 discounted_amount: '10.0' display_discounted_amount: $10.00 display_compare_at_amount: $0.00 compare_at_amount: null thumbnail_url: null option_values: [] digital_links: [] fulfillments: - id: ful_UkLWZg9DAJ number: H26728427796 tracking: U10000 tracking_url: null cost: '100.0' display_cost: $100.00 total: '100.0' display_total: $100.00 discount_total: '0.0' display_discount_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 tax_total: '0.0' display_tax_total: $0.00 status: pending fulfillment_type: shipping fulfilled_at: null items: - item_id: li_UkLWZg9DAJ variant_id: variant_UkLWZg9DAJ quantity: 1 delivery_method: id: dm_UkLWZg9DAJ name: UPS Ground code: UPS_GROUND stock_location: id: sloc_UkLWZg9DAJ state_abbr: NY name: Maida Rogahn address1: 1600 Pennsylvania Ave NW city: Washington zipcode: '20500' country_iso: US country_name: United States of America state_text: NY delivery_rates: - id: dr_gbHJdmfrXB delivery_method_id: dm_UkLWZg9DAJ name: UPS Ground selected: true cost: '10.0' total: '10.0' additional_tax_total: '0.0' included_tax_total: '0.0' tax_total: '0.0' display_cost: $10.00 display_total: $10.00 display_additional_tax_total: $0.00 display_included_tax_total: $0.00 display_tax_total: $0.00 delivery_method: id: dm_UkLWZg9DAJ name: UPS Ground code: UPS_GROUND payments: [] billing_address: id: addr_UkLWZg9DAJ first_name: John last_name: Doe full_name: John Doe address1: 256 Lovely Street address2: Northwest postal_code: '10118' city: New York phone: 555-555-0199 company: Company country_name: United States of America country_iso: US state_text: NY state_abbr: NY quick_checkout: false is_default_billing: false is_default_shipping: false state_name: New York shipping_address: id: addr_gbHJdmfrXB first_name: John last_name: Doe full_name: John Doe address1: 257 Lovely Street address2: Northwest postal_code: '10118' city: New York phone: 555-555-0199 company: Company country_name: United States of America country_iso: US state_text: NY state_abbr: NY quick_checkout: false is_default_billing: false is_default_shipping: false state_name: New York gift_card: null market: null schema: $ref: '#/components/schemas/Order' '404': description: incomplete order not accessible content: application/json: example: error: code: order_not_found message: Order not found schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: LineItem: type: object properties: id: type: string variant_id: type: string quantity: type: number currency: type: string name: type: string slug: type: string options_text: type: string price: type: string display_price: type: string total: type: string display_total: type: string adjustment_total: type: string display_adjustment_total: type: string additional_tax_total: type: string display_additional_tax_total: type: string included_tax_total: type: string display_included_tax_total: type: string discount_total: type: string display_discount_total: type: string pre_tax_amount: type: string display_pre_tax_amount: type: string discounted_amount: type: string display_discounted_amount: type: string display_compare_at_amount: type: string nullable: true compare_at_amount: type: string nullable: true thumbnail_url: type: string nullable: true option_values: type: array items: $ref: '#/components/schemas/OptionValue' digital_links: type: array items: $ref: '#/components/schemas/DigitalLink' required: - id - variant_id - quantity - currency - name - slug - options_text - price - display_price - total - display_total - adjustment_total - display_adjustment_total - additional_tax_total - display_additional_tax_total - included_tax_total - display_included_tax_total - discount_total - display_discount_total - pre_tax_amount - display_pre_tax_amount - discounted_amount - display_discounted_amount - display_compare_at_amount - compare_at_amount - thumbnail_url - option_values - digital_links x-typelizer: true error: type: object properties: error: type: string required: - error x-internal: false PaymentSource: type: object properties: id: type: string gateway_payment_profile_id: type: string nullable: true required: - id - gateway_payment_profile_id x-typelizer: true Address: type: object properties: id: type: string first_name: type: string nullable: true last_name: type: string nullable: true full_name: type: string address1: type: string nullable: true address2: type: string nullable: true postal_code: type: string nullable: true city: type: string nullable: true phone: type: string nullable: true company: type: string nullable: true country_name: type: string country_iso: type: string state_text: type: string nullable: true state_abbr: type: string nullable: true quick_checkout: type: boolean is_default_billing: type: boolean is_default_shipping: type: boolean state_name: type: string nullable: true required: - id - first_name - last_name - full_name - address1 - address2 - postal_code - city - phone - company - country_name - country_iso - state_text - state_abbr - quick_checkout - is_default_billing - is_default_shipping - state_name x-typelizer: true resource: type: object properties: data: $ref: '#/components/schemas/resource_properties' required: - data x-internal: false DeliveryRate: type: object properties: id: type: string delivery_method_id: type: string name: type: string selected: type: boolean cost: type: string total: type: string additional_tax_total: type: string included_tax_total: type: string tax_total: type: string display_cost: type: string display_total: type: string display_additional_tax_total: type: string display_included_tax_total: type: string display_tax_total: type: string delivery_method: $ref: '#/components/schemas/DeliveryMethod' required: - id - delivery_method_id - name - selected - cost - total - additional_tax_total - included_tax_total - tax_total - display_cost - display_total - display_additional_tax_total - display_included_tax_total - display_tax_total - delivery_method x-typelizer: true ErrorResponse: type: object properties: error: type: object properties: code: type: string example: record_not_found message: type: string example: Record not found details: type: object description: Field-specific validation errors nullable: true example: name: - is too short - is required email: - is invalid required: - code - message required: - error example: error: code: validation_error message: Validation failed details: name: - is too short email: - is invalid FulfillmentManifestItem: type: object description: An item within a fulfillment — which line item and how many units are in this fulfillment properties: item_id: type: string description: Line item ID example: li_abc123 variant_id: type: string description: Variant ID example: variant_abc123 quantity: type: integer description: Quantity in this fulfillment example: 2 required: - item_id - variant_id - quantity resource_properties: type: object properties: id: type: string type: type: string attributes: type: object relationships: type: object required: - id - type - attributes x-internal: false DeliveryMethod: type: object properties: id: type: string name: type: string code: type: string nullable: true required: - id - name - code x-typelizer: true Fulfillment: type: object properties: id: type: string number: type: string tracking: type: string nullable: true tracking_url: type: string nullable: true cost: type: string display_cost: type: string total: type: string display_total: type: string discount_total: type: string display_discount_total: type: string additional_tax_total: type: string display_additional_tax_total: type: string included_tax_total: type: string display_included_tax_total: type: string tax_total: type: string display_tax_total: type: string status: type: string fulfillment_type: type: string fulfilled_at: type: string nullable: true items: type: array items: $ref: '#/components/schemas/FulfillmentManifestItem' delivery_method: $ref: '#/components/schemas/DeliveryMethod' stock_location: $ref: '#/components/schemas/StockLocation' delivery_rates: type: array items: $ref: '#/components/schemas/DeliveryRate' required: - id - number - tracking - tracking_url - cost - display_cost - total - display_total - discount_total - display_discount_total - additional_tax_total - display_additional_tax_total - included_tax_total - display_included_tax_total - tax_total - display_tax_total - status - fulfillment_type - fulfilled_at - items - delivery_method - stock_location - delivery_rates x-typelizer: true update_order_params: type: object properties: order: type: object properties: item_total: type: number example: 170.9 total: type: number example: 190.9 state: type: string example: complete enum: - cart - address - delivery - payment - confirm - complete - canceled adjustment_total: type: number example: 20.0 user_id: type: string example: '1' completed_at: type: string format: date_time example: 2022-11-08 19:33:50 UTC bill_address_id: type: string example: '1' ship_address_id: type: string example: '1' payment_total: type: number example: 190.9 shipment_state: type: string example: shipped enum: - backorder - canceled - partial - pending - ready - shipped payment_state: type: string example: paid enum: - balance_due - credit_owed - failed - paid - void email: type: string format: email example: hi@getvendo.com special_instructions: type: string example: I need it ASAP! currency: type: string example: USD last_ip_address: type: string example: 127.0.0.1 created_by_id: type: string example: '1' shipment_total: type: number example: 10.0 additional_tax_total: type: number example: 10.0 promo_total: type: number example: 0.0 channel: type: string example: online included_tax_total: type: number example: 0.0 item_count: type: integer example: 2 approver_id: type: string approved_at: type: string format: date_time example: 2022-11-08 19:33:50 UTC confirmation_delivered: type: boolean example: true default: false considered_risky: type: boolean example: true default: false canceled_at: type: string format: date_time canceler_id: type: string taxable_adjustment_total: type: number example: 170.9 non_taxable_adjustment_total: type: number example: 10.0 store_owner_notification_delivered: type: boolean example: true default: false bill_address_attributes: $ref: '#/components/schemas/update_address_params' ship_address_attributes: $ref: '#/components/schemas/update_address_params' line_items_attributes: type: array items: $ref: '#/components/schemas/update_line_item_params' public_metadata: type: object private_metadata: type: object required: - order x-internal: false resources_list: type: object properties: data: type: array items: allOf: - $ref: '#/components/schemas/resource_properties' meta: type: object properties: count: type: integer total_count: type: integer total_pages: type: integer required: - count - total_count - total_pages links: type: object properties: self: type: string next: type: string prev: type: string last: type: string first: type: string required: - self - next - prev - last - first required: - data - meta - links x-internal: false amount_param: type: object properties: amount: type: number x-internal: false DigitalLink: type: object properties: id: type: string access_counter: type: number filename: type: string content_type: type: string download_url: type: string authorizable: type: boolean expired: type: boolean access_limit_exceeded: type: boolean required: - id - access_counter - filename - content_type - download_url - authorizable - expired - access_limit_exceeded x-typelizer: true Market: type: object properties: id: type: string name: type: string currency: type: string default_locale: type: string tax_inclusive: type: boolean default: type: boolean country_isos: type: array items: type: string supported_locales: type: array items: type: string countries: type: array items: $ref: '#/components/schemas/Country' required: - id - name - currency - default_locale - tax_inclusive - default - country_isos - supported_locales x-typelizer: true coupon_code_param: type: object properties: coupon_code: type: string x-internal: false Discount: type: object properties: id: type: string promotion_id: type: string name: type: string description: type: string nullable: true code: type: string nullable: true amount: type: string display_amount: type: string required: - id - promotion_id - name - description - code - amount - display_amount x-typelizer: true CreditCard: type: object properties: id: type: string brand: type: string last4: type: string month: type: number year: type: number name: type: string nullable: true default: type: boolean gateway_payment_profile_id: type: string nullable: true required: - id - brand - last4 - month - year - name - default - gateway_payment_profile_id x-typelizer: true StockLocation: type: object properties: id: type: string state_abbr: type: string nullable: true name: type: string address1: type: string nullable: true city: type: string nullable: true zipcode: type: string nullable: true country_iso: type: string nullable: true country_name: type: string nullable: true state_text: type: string nullable: true required: - id - state_abbr - name - address1 - city - zipcode - country_iso - country_name - state_text x-typelizer: true State: type: object properties: abbr: type: string name: type: string required: - abbr - name x-typelizer: true PaymentMethod: type: object properties: id: type: string name: type: string description: type: string nullable: true type: type: string session_required: type: boolean source_required: type: boolean required: - id - name - description - type - session_required - source_required x-typelizer: true GiftCard: type: object properties: id: type: string code: type: string status: type: string currency: type: string amount: type: string amount_used: type: string amount_authorized: type: string amount_remaining: type: string display_amount: type: string display_amount_used: type: string display_amount_remaining: type: string expires_at: type: string nullable: true redeemed_at: type: string nullable: true expired: type: boolean active: type: boolean required: - id - code - status - currency - amount - amount_used - amount_authorized - amount_remaining - display_amount - display_amount_used - display_amount_remaining - expires_at - redeemed_at - expired - active x-typelizer: true Order: type: object properties: id: type: string market_id: type: string nullable: true channel_id: type: string nullable: true number: type: string email: type: string customer_note: type: string nullable: true currency: type: string locale: type: string nullable: true total_quantity: type: number item_total: type: string display_item_total: type: string adjustment_total: type: string display_adjustment_total: type: string discount_total: type: string display_discount_total: type: string tax_total: type: string display_tax_total: type: string included_tax_total: type: string display_included_tax_total: type: string additional_tax_total: type: string display_additional_tax_total: type: string total: type: string display_total: type: string gift_card_total: type: string display_gift_card_total: type: string amount_due: type: string display_amount_due: type: string delivery_total: type: string display_delivery_total: type: string fulfillment_status: type: string nullable: true payment_status: type: string nullable: true completed_at: type: string nullable: true store_credit_total: type: string display_store_credit_total: type: string covered_by_store_credit: type: boolean discounts: type: array items: $ref: '#/components/schemas/Discount' items: type: array items: $ref: '#/components/schemas/LineItem' fulfillments: type: array items: $ref: '#/components/schemas/Fulfillment' payments: type: array items: $ref: '#/components/schemas/Payment' billing_address: allOf: - $ref: '#/components/schemas/Address' nullable: true shipping_address: allOf: - $ref: '#/components/schemas/Address' nullable: true gift_card: allOf: - $ref: '#/components/schemas/GiftCard' nullable: true market: allOf: - $ref: '#/components/schemas/Market' nullable: true required: - id - market_id - channel_id - number - email - customer_note - currency - locale - total_quantity - item_total - display_item_total - adjustment_total - display_adjustment_total - discount_total - display_discount_total - tax_total - display_tax_total - included_tax_total - display_included_tax_total - additional_tax_total - display_additional_tax_total - total - display_total - gift_card_total - display_gift_card_total - amount_due - display_amount_due - delivery_total - display_delivery_total - fulfillment_status - payment_status - completed_at - store_credit_total - display_store_credit_total - covered_by_store_credit - discounts - items - fulfillments - payments - billing_address - shipping_address - gift_card - market x-typelizer: true create_order_params: type: object properties: order: type: object properties: item_total: type: number example: 170.9 total: type: number example: 190.9 state: type: string example: complete enum: - cart - address - delivery - payment - confirm - complete - canceled adjustment_total: type: number example: 20.0 user_id: type: string example: '1' completed_at: type: string format: date_time example: 2022-11-08 19:33:50 UTC bill_address_id: type: string example: '1' ship_address_id: type: string example: '1' payment_total: type: number example: 190.9 shipment_state: type: string example: shipped enum: - backorder - canceled - partial - pending - ready - shipped payment_state: type: string example: paid enum: - balance_due - credit_owed - failed - paid - void email: type: string format: email example: hi@getvendo.com special_instructions: type: string example: I need it ASAP! currency: type: string example: USD last_ip_address: type: string example: 127.0.0.1 created_by_id: type: string example: '1' shipment_total: type: number example: 10.0 additional_tax_total: type: number example: 10.0 promo_total: type: number example: 0.0 channel: type: string example: online included_tax_total: type: number example: 0.0 item_count: type: integer example: 2 approver_id: type: string approved_at: type: string format: date_time example: 2022-11-08 19:33:50 UTC confirmation_delivered: type: boolean example: true default: false considered_risky: type: boolean example: true default: false canceled_at: type: string format: date_time canceler_id: type: string taxable_adjustment_total: type: number example: 170.9 non_taxable_adjustment_total: type: number example: 10.0 store_owner_notification_delivered: type: boolean example: true default: false bill_address_attributes: $ref: '#/components/schemas/update_address_params' ship_address_attributes: $ref: '#/components/schemas/update_address_params' line_items_attributes: type: array items: $ref: '#/components/schemas/update_line_item_params' public_metadata: type: object private_metadata: type: object required: - order x-internal: false validation_errors: type: object properties: error: type: string errors: type: object required: - error - errors x-internal: false Country: type: object properties: iso: type: string iso3: type: string name: type: string states_required: type: boolean zipcode_required: type: boolean states: type: array items: $ref: '#/components/schemas/State' market: allOf: - $ref: '#/components/schemas/Market' nullable: true required: - iso - iso3 - name - states_required - zipcode_required 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 required: - id - option_type_id - name - label - position - color_code - option_type_name - option_type_label - image_url x-typelizer: true update_line_item_params: type: object properties: line_item: type: object properties: variant_id: type: string example: '1' quantity: type: integer example: 2 required: - line_item x-internal: false StoreCredit: type: object properties: id: type: string amount: type: string amount_used: type: string amount_remaining: type: string display_amount: type: string display_amount_used: type: string display_amount_remaining: type: string currency: type: string required: - id - amount - amount_used - amount_remaining - display_amount - display_amount_used - display_amount_remaining - currency x-typelizer: true update_address_params: type: object properties: address: type: object properties: country_id: type: string example: '224' state_id: type: string example: '516' state_name: type: string example: New York address1: type: string example: 5th ave address2: type: string example: 1st suite city: type: string example: NY zipcode: type: string example: '10001' phone: type: string example: +1 123 456 789 alternative_phone: type: string firstname: type: string example: John lastname: type: string example: Snow label: type: string example: My home address company: type: string example: Vendo Connect Inc user_id: type: string public_metadata: type: object example: distance_from_city_in_km: 10 location_type: building private_metadata: type: object example: close_to_shop: true required: - address x-internal: false Payment: type: object properties: id: type: string payment_method_id: type: string response_code: type: string nullable: true number: type: string amount: type: string display_amount: type: string status: type: string source_type: type: string nullable: true enum: - credit_card - store_credit - payment_source source_id: type: string nullable: true source: anyOf: - $ref: '#/components/schemas/CreditCard' - $ref: '#/components/schemas/StoreCredit' - $ref: '#/components/schemas/PaymentSource' nullable: true payment_method: $ref: '#/components/schemas/PaymentMethod' required: - id - payment_method_id - response_code - number - amount - display_amount - status - source_type - source_id - source - payment_method x-typelizer: true 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