Spree Seller SDK

import { createSellerClient } from '@spree/seller-sdk'

const client = createSellerClient({
  baseUrl: 'https://your-store.com',
  jwtToken: 'eyJhbGciOi...',
  sellerId: 'sel_UkLWZg9DAJ',
})

const order = await client.orders.cancel('or_UkLWZg9DAJ', {
  cancel_reason_id: 'ocr_UkLWZg9DAJ',
  cancel_note: 'Out of stock with the supplier',
  refund_payments: true,
})

curl --request PATCH \
  --url http://{defaultHost}/api/v3/seller/orders/{id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Spree-Seller-Id: <x-spree-seller-id>' \
  --data '
{
  "cancel_reason_id": "<string>",
  "cancel_note": "<string>",
  "refund_payments": true,
  "notify_customer": true
}
'

{
  "id": "or_UkLWZg9DAJ",
  "number": "R1001",
  "customer_note": null,
  "currency": "USD",
  "total_quantity": 1,
  "status": "canceled",
  "fulfillment_status": "canceled",
  "payment_status": "none",
  "completed_at": "2026-01-15T12:00:00.000Z",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "internal_note": null,
  "internal_note_html": null,
  "item_total": "10.00",
  "delivery_total": "100.00",
  "discount_total": "0.00",
  "adjustment_total": "0.00",
  "included_tax_total": "0.00",
  "additional_tax_total": "0.00",
  "tax_total": "0.00",
  "total": "110.00",
  "payment_total": "0.00",
  "amount_due": "0.00",
  "commission_amount_total": "0.00",
  "commission_tax_total": "0.00",
  "commission_total": "0.00",
  "canceled_at": "2026-01-15T12:00:00Z",
  "cancel_reason_name": null,
  "cancel_note": null,
  "items": [
    {
      "id": "li_UkLWZg9DAJ",
      "name": "Product 2746554",
      "options_text": "",
      "quantity": 1,
      "currency": "USD",
      "price": "10.00",
      "discounted_amount": "10.00",
      "additional_tax_total": "0.00",
      "total": "10.00",
      "variant_id": "variant_UkLWZg9DAJ",
      "sku": "SKU-360",
      "thumbnail_url": null
    }
  ],
  "fulfillments": [
    {
      "id": "ful_UkLWZg9DAJ",
      "number": "R1001-F1",
      "status": "canceled",
      "tracking": "U10000",
      "tracking_url": null,
      "fulfilled_at": null,
      "delivered_at": null,
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z",
      "fulfillment_type": "shipping",
      "delivery_method_name": "UPS Ground 150",
      "stock_location_name": "Savanna Hills",
      "stock_location_id": "sloc_UkLWZg9DAJ",
      "fulfillment_items": [
        {
          "id": "fi_UkLWZg9DAJ",
          "quantity": 1,
          "line_item_id": "li_UkLWZg9DAJ",
          "variant_id": "variant_UkLWZg9DAJ",
          "name": "Product 2746554",
          "sku": "SKU-360",
          "options_text": ""
        }
      ],
      "selected_delivery_rate_id": "dr_gbHJdmfrXB",
      "delivery_rates": [
        {
          "id": "dr_gbHJdmfrXB",
          "name": "UPS Ground 150",
          "selected": true,
          "cost": "10.00",
          "total": "10.00",
          "carrier": null,
          "service_level": null,
          "estimated_delivery_date": null,
          "unpriced": false
        }
      ],
      "deliveries": [
        {
          "id": "dlv_UkLWZg9DAJ",
          "tracking_number": "U10000",
          "carrier": null,
          "carrier_name": null,
          "service": null,
          "status": "pending",
          "tracking_url": null,
          "estimated_delivery_at": null,
          "delivered_at": null,
          "created_at": "2026-01-15T12:00:00.000Z",
          "updated_at": "2026-01-15T12:00:00.000Z",
          "shipping_label_id": null
        }
      ],
      "labels": []
    }
  ],
  "shipping_address": {
    "id": "addr_gbHJdmfrXB",
    "label": null,
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "address1": "290 Lovely Street",
    "address2": "Northwest",
    "postal_code": "10118",
    "city": "New York",
    "phone": "555-555-0199",
    "company": "Company",
    "country_name": "United States",
    "country_code": "US",
    "state_text": "NY",
    "state_code": "NY",
    "quick_checkout": false,
    "is_default_billing": false,
    "is_default_shipping": false,
    "state_name": "New York"
  },
  "billing_address": {
    "id": "addr_UkLWZg9DAJ",
    "label": null,
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "address1": "289 Lovely Street",
    "address2": "Northwest",
    "postal_code": "10118",
    "city": "New York",
    "phone": "555-555-0199",
    "company": "Company",
    "country_name": "United States",
    "country_code": "US",
    "state_text": "NY",
    "state_code": "NY",
    "quick_checkout": false,
    "is_default_billing": false,
    "is_default_shipping": false,
    "state_name": "New York"
  }
}

Cancel an order

Withdraws from an order this seller cannot fulfil, naming a reason from the marketplace’s own list.

The goods go back on the shelf and the payment authorization is released either way. refund_payments also hands back what the buyer paid for these goods — a seller is merchant of record for their own child order, and on a split checkout only that order’s share of the group’s payment is settled.

There is no refund_amount: withdrawing from the whole order returns what that order was paid, and a partial figure is a return.

PATCH

api

seller

orders

{id}

cancel

Spree Seller SDK

import { createSellerClient } from '@spree/seller-sdk'

const client = createSellerClient({
  baseUrl: 'https://your-store.com',
  jwtToken: 'eyJhbGciOi...',
  sellerId: 'sel_UkLWZg9DAJ',
})

const order = await client.orders.cancel('or_UkLWZg9DAJ', {
  cancel_reason_id: 'ocr_UkLWZg9DAJ',
  cancel_note: 'Out of stock with the supplier',
  refund_payments: true,
})

curl --request PATCH \
  --url http://{defaultHost}/api/v3/seller/orders/{id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Spree-Seller-Id: <x-spree-seller-id>' \
  --data '
{
  "cancel_reason_id": "<string>",
  "cancel_note": "<string>",
  "refund_payments": true,
  "notify_customer": true
}
'

{
  "id": "or_UkLWZg9DAJ",
  "number": "R1001",
  "customer_note": null,
  "currency": "USD",
  "total_quantity": 1,
  "status": "canceled",
  "fulfillment_status": "canceled",
  "payment_status": "none",
  "completed_at": "2026-01-15T12:00:00.000Z",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "internal_note": null,
  "internal_note_html": null,
  "item_total": "10.00",
  "delivery_total": "100.00",
  "discount_total": "0.00",
  "adjustment_total": "0.00",
  "included_tax_total": "0.00",
  "additional_tax_total": "0.00",
  "tax_total": "0.00",
  "total": "110.00",
  "payment_total": "0.00",
  "amount_due": "0.00",
  "commission_amount_total": "0.00",
  "commission_tax_total": "0.00",
  "commission_total": "0.00",
  "canceled_at": "2026-01-15T12:00:00Z",
  "cancel_reason_name": null,
  "cancel_note": null,
  "items": [
    {
      "id": "li_UkLWZg9DAJ",
      "name": "Product 2746554",
      "options_text": "",
      "quantity": 1,
      "currency": "USD",
      "price": "10.00",
      "discounted_amount": "10.00",
      "additional_tax_total": "0.00",
      "total": "10.00",
      "variant_id": "variant_UkLWZg9DAJ",
      "sku": "SKU-360",
      "thumbnail_url": null
    }
  ],
  "fulfillments": [
    {
      "id": "ful_UkLWZg9DAJ",
      "number": "R1001-F1",
      "status": "canceled",
      "tracking": "U10000",
      "tracking_url": null,
      "fulfilled_at": null,
      "delivered_at": null,
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z",
      "fulfillment_type": "shipping",
      "delivery_method_name": "UPS Ground 150",
      "stock_location_name": "Savanna Hills",
      "stock_location_id": "sloc_UkLWZg9DAJ",
      "fulfillment_items": [
        {
          "id": "fi_UkLWZg9DAJ",
          "quantity": 1,
          "line_item_id": "li_UkLWZg9DAJ",
          "variant_id": "variant_UkLWZg9DAJ",
          "name": "Product 2746554",
          "sku": "SKU-360",
          "options_text": ""
        }
      ],
      "selected_delivery_rate_id": "dr_gbHJdmfrXB",
      "delivery_rates": [
        {
          "id": "dr_gbHJdmfrXB",
          "name": "UPS Ground 150",
          "selected": true,
          "cost": "10.00",
          "total": "10.00",
          "carrier": null,
          "service_level": null,
          "estimated_delivery_date": null,
          "unpriced": false
        }
      ],
      "deliveries": [
        {
          "id": "dlv_UkLWZg9DAJ",
          "tracking_number": "U10000",
          "carrier": null,
          "carrier_name": null,
          "service": null,
          "status": "pending",
          "tracking_url": null,
          "estimated_delivery_at": null,
          "delivered_at": null,
          "created_at": "2026-01-15T12:00:00.000Z",
          "updated_at": "2026-01-15T12:00:00.000Z",
          "shipping_label_id": null
        }
      ],
      "labels": []
    }
  ],
  "shipping_address": {
    "id": "addr_gbHJdmfrXB",
    "label": null,
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "address1": "290 Lovely Street",
    "address2": "Northwest",
    "postal_code": "10118",
    "city": "New York",
    "phone": "555-555-0199",
    "company": "Company",
    "country_name": "United States",
    "country_code": "US",
    "state_text": "NY",
    "state_code": "NY",
    "quick_checkout": false,
    "is_default_billing": false,
    "is_default_shipping": false,
    "state_name": "New York"
  },
  "billing_address": {
    "id": "addr_UkLWZg9DAJ",
    "label": null,
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "address1": "289 Lovely Street",
    "address2": "Northwest",
    "postal_code": "10118",
    "city": "New York",
    "phone": "555-555-0199",
    "company": "Company",
    "country_name": "United States",
    "country_code": "US",
    "state_text": "NY",
    "state_code": "NY",
    "quick_checkout": false,
    "is_default_billing": false,
    "is_default_shipping": false,
    "state_name": "New York"
  }
}

Authorizations

Authorization

string

header

required

JWT token for an authenticated seller session (seller_api audience)

Headers

X-Spree-Seller-Id

string

required

Path Parameters

string

required

Prefixed order ID

Body

application/json

cancel_reason_id

string | null

A reason from the order cancellation reasons endpoint.

cancel_note

string | null

Free text beside the reason.

refund_payments

boolean

Hand back what the buyer paid for this order's goods.

notify_customer

boolean

Email the customer about the cancellation.

Response

200 - application/json

order canceled

string

required

number

string

required

customer_note

string | null

required

currency

enum<string>

required

Available options:

AED,

AFN,

ALL,

AMD,

ANG,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BTN,

BWP,

BYN,

BYR,

BZD,

CAD,

CDF,

CHF,

CLF,

CLP,

CNY,

COP,

CRC,

CUC,

CUP,

CVE,

CZK,

DJF,

DKK,

DOP,

DZD,

EEK,

EGP,

ERN,

ETB,

EUR,

FJD,

FKP,

GBP,

GEL,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

INR,

IQD,

IRR,

ISK,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KPW,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LTL,

LVL,

LYD,

MAD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRO,

MRU,

MTL,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

NGN,

NIO,

NOK,

NPR,

NZD,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SDG,

SEK,

SGD,

SHP,

SKK,

SLE,

SLL,

SOS,

SRD,

SSP,

STD,

STN,

SVC,

SYP,

SZL,

THB,

TJS,

TMM,

TMT,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYI,

UYU,

UYW,

UZS,

VED,

VEF,

VES,

VND,

VUV,

WST,

XAF,

XCD,

XCG,

XOF,

XPF,

YER,

ZAR,

ZMK,

ZMW,

ZWD,

ZWG,

ZWL,

ZWN,

ZWR

total_quantity

number

required

status

enum<string>

required

Available options:

draft,

placed,

canceled

fulfillment_status

enum<string> | null

required

Available options:

backorder,

canceled,

partial,

unfulfilled,

fulfilled,

delivered,

pending,

ready,

shipped

payment_status

enum<string> | null

required

Available options:

none,

authorized,

partially_paid,

paid,

partially_refunded,

refunded,

overcharged,

voided

completed_at

string

required

created_at

string

required

updated_at

string

required

internal_note

string | null

required

internal_note_html

string | null

required

item_total

string | null

required

delivery_total

string | null

required

discount_total

string | null

required

adjustment_total

string | null

required

included_tax_total

string | null

required

additional_tax_total

string | null

required

tax_total

string | null

required

total

string | null

required

payment_total

string | null

required

amount_due

string | null

required

commission_amount_total

string | null

required

commission_tax_total

string | null

required

commission_total

string | null

required

canceled_at

string | null

required

cancel_reason_name

string | null

required

cancel_note

string | null

required

items

object[]

required

Show child attributes

fulfillments

object[]

required

Show child attributes

shipping_address

object

required

Show child attributes

billing_address

object

required

Show child attributes

payment_splits

object[]

Show child attributes

⌘I

API basics

Endpoints

Cancel an order

Authorizations

Headers

Path Parameters

Body

Response