Spree Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

// A split checkout: the payment is shared, so what comes back is this order's
// own share. refund_amount names part of that share, keeping the rest back.
const order = await client.orders.cancel('or_UkLWZg9DAJ', {
  cancel_reason_id: 'ocr_UkLWZg9DAJ',
  cancel_note: 'Supplier could not deliver in time',
  refund_payments: true,
  refund_amount: '25.00',
})

{
  "id": "or_UkLWZg9DAJ",
  "market_id": "mkt_UkLWZg9DAJ",
  "withdrawal_period_ends_at": null,
  "within_withdrawal_period": false,
  "cart_id": null,
  "channel_id": "ch_UkLWZg9DAJ",
  "company_id": null,
  "company_name": null,
  "po_document_filename": null,
  "po_document_byte_size": null,
  "number": "R1001",
  "email": "eleanor@zulaufdavis.com",
  "customer_note": null,
  "po_number": null,
  "currency": "USD",
  "locale": "en",
  "total_quantity": 1,
  "coupon_code": null,
  "fulfillment_status": "canceled",
  "payment_status": "none",
  "completed_at": "2026-01-15T12:00:00.000Z",
  "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",
  "fee_total": "0.0",
  "display_fee_total": "$0.00",
  "store_credit_total": "0.0",
  "display_store_credit_total": "$0.00",
  "covered_by_store_credit": false,
  "gift_card": null,
  "market": {
    "id": "mkt_UkLWZg9DAJ",
    "name": "United States",
    "currency": "USD",
    "default_locale": "en",
    "tax_inclusive": false,
    "default": true,
    "country_codes": [
      "US"
    ],
    "supported_locales": [
      "en"
    ],
    "tax_provider": null,
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  },
  "external_references": {},
  "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": {},
  "cancel_note": null,
  "commission_amount_total": "0.0",
  "display_commission_amount_total": "$0.00",
  "commission_tax_total": "0.0",
  "display_commission_tax_total": "$0.00",
  "commission_total": "0.0",
  "display_commission_total": "$0.00",
  "canceled_at": "2026-01-15T12:00:00.000Z",
  "approved_at": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "preferred_stock_location_id": null,
  "po_document_url": null,
  "seller_id": null,
  "order_group_id": null,
  "tags": [],
  "internal_note": null,
  "internal_note_html": null,
  "approver_id": null,
  "approver_type": null,
  "canceler_id": "adm_UkLWZg9DAJ",
  "canceler_type": "admin_user",
  "created_by_id": null,
  "created_by_type": null,
  "cancel_reason_id": null,
  "cancel_reason_name": null,
  "customer_id": "cust_UkLWZg9DAJ",
  "freight_summary": null
}

Cancel an order

Cancels a completed order.

cancel_reason_id records why, from the store’s own cancellation-reason vocabulary (/admin/order_cancellation_reasons), and cancel_note is a staff-facing note; both are shown on the order afterwards.

Stock is always released — the goods are not going out either way — and every payment is settled at the gateway, which releases an authorization it never drew on and refunds a charge it cannot release.

refund_payments and refund_amount govern the shared payment of a split checkout, where one payment covers several orders: they decide whether this order’s share comes back, and how much of it. A refund_amount on an ordinary order is refused with a 422.

Set notify_customer: true to send the order cancellation email.

Required scope: write_orders (for API-key authentication).

PATCH

api

admin

orders

{id}

cancel

Spree Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

// A split checkout: the payment is shared, so what comes back is this order's
// own share. refund_amount names part of that share, keeping the rest back.
const order = await client.orders.cancel('or_UkLWZg9DAJ', {
  cancel_reason_id: 'ocr_UkLWZg9DAJ',
  cancel_note: 'Supplier could not deliver in time',
  refund_payments: true,
  refund_amount: '25.00',
})

{
  "id": "or_UkLWZg9DAJ",
  "market_id": "mkt_UkLWZg9DAJ",
  "withdrawal_period_ends_at": null,
  "within_withdrawal_period": false,
  "cart_id": null,
  "channel_id": "ch_UkLWZg9DAJ",
  "company_id": null,
  "company_name": null,
  "po_document_filename": null,
  "po_document_byte_size": null,
  "number": "R1001",
  "email": "eleanor@zulaufdavis.com",
  "customer_note": null,
  "po_number": null,
  "currency": "USD",
  "locale": "en",
  "total_quantity": 1,
  "coupon_code": null,
  "fulfillment_status": "canceled",
  "payment_status": "none",
  "completed_at": "2026-01-15T12:00:00.000Z",
  "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",
  "fee_total": "0.0",
  "display_fee_total": "$0.00",
  "store_credit_total": "0.0",
  "display_store_credit_total": "$0.00",
  "covered_by_store_credit": false,
  "gift_card": null,
  "market": {
    "id": "mkt_UkLWZg9DAJ",
    "name": "United States",
    "currency": "USD",
    "default_locale": "en",
    "tax_inclusive": false,
    "default": true,
    "country_codes": [
      "US"
    ],
    "supported_locales": [
      "en"
    ],
    "tax_provider": null,
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  },
  "external_references": {},
  "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": {},
  "cancel_note": null,
  "commission_amount_total": "0.0",
  "display_commission_amount_total": "$0.00",
  "commission_tax_total": "0.0",
  "display_commission_tax_total": "$0.00",
  "commission_total": "0.0",
  "display_commission_total": "$0.00",
  "canceled_at": "2026-01-15T12:00:00.000Z",
  "approved_at": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "preferred_stock_location_id": null,
  "po_document_url": null,
  "seller_id": null,
  "order_group_id": null,
  "tags": [],
  "internal_note": null,
  "internal_note_html": null,
  "approver_id": null,
  "approver_type": null,
  "canceler_id": "adm_UkLWZg9DAJ",
  "canceler_type": "admin_user",
  "created_by_id": null,
  "created_by_type": null,
  "cancel_reason_id": null,
  "cancel_reason_name": null,
  "customer_id": "cust_UkLWZg9DAJ",
  "freight_summary": null
}

Authorizations

x-spree-api-key

string

header

required

Secret API key for admin access

Authorization

string

header

required

JWT token for admin user authentication

Headers

x-spree-api-key

string

required

Authorization

string

required

Bearer token for admin authentication

Path Parameters

string

required

Order ID

Body

application/json

cancel_reason_id

string

Why the order was canceled — the id of one of the store's cancellation reasons.

cancel_note

string

Staff-facing note about the cancellation.

refund_payments

boolean

default:false

Whether this order's share of a payment shared across a split checkout is handed back.

refund_amount

string

How much of that share to return. Defaults to all of it; refused on an order whose payment is not shared.

notify_customer

boolean

default:false

Send the order cancellation email after canceling.

Response

200 - application/json

order canceled

⌘I

API basics

Endpoints

Cancel an order

Authorizations

Headers

Path Parameters

Body

Response