API reference

Orders

Orders, fulfillments, cancellations, refunds and notes.

On this page

List orders
Create an order
Get an order
Update an order's tags and note
Fulfil an order
Cancel an order
Refund an order
Add a note to an order

List orders

get/orders

Required scopes:read_orders

Query parameters

Name	Type	Description
`limit`	integer	Page size, 1–250 (default 50). default 50 · min 1 · max 250
`cursor`	string	next_cursor from the previous page.
`updated_since`	string<date-time>	Only objects changed at or after this ISO-8601 time.
`created_since`	string<date-time>	Only objects created at or after this ISO-8601 time.
`status`	string	Order status. One of:`pendingprocessingon_holdshippedready_for_pickupdeliveredcancelledrefunded`
`payment_status`	string	Payment status. One of:`unpaidauthorizedpaidpartially_refundedrefundedfailed`
`customer_id`	integer	Of this customer.
`source`	string	storefront, pos, subscription or api.
`email`	string	Customer email.

Example request

curl

curl "https://api.sellorchard.com/v1/orders?limit=50" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY"

Response200Orders, newest first.

Show response schema

dataarray of Orderrequired
ShowHide item attributes
- objectstringrequired
- idintegerrequired
  Order id.
- numberintegerrequired
  Order number.
- namestringrequired
  Number with the store prefix.
- statusstringrequired
  Order status.
  One of:pendingprocessingon_holdshippedready_for_pickupdeliveredcancelledrefunded
- payment_statusstringrequired
  Payment status.
  One of:unpaidauthorizedpaidpartially_refundedrefundedfailed
- fulfillment_statusstringrequired
  unfulfilled, partial (some lines shipped) or fulfilled.
  One of:unfulfilledpartialfulfilled
- sourcestringrequired
  Where it was placed.
  One of:storefrontpossubscriptionapi
- testbooleanrequired
  A test order (free-trial store).
- emailstring<email> | nullrequired
  Customer email.
- phonestring | nullrequired
  Phone.
- customer_idinteger | nullrequired
  Customer.
- customer_namestring | nullrequired
  Name.
- currencystringrequired
  ISO 4217 currency of every amount on the order.
- subtotalstringrequired
  Lines before discounts.
  pattern ^-?\d+\.\d{2}$
- discount_totalstringrequired
  Discounts.
  pattern ^-?\d+\.\d{2}$
- shipping_totalstringrequired
  Shipping.
  pattern ^-?\d+\.\d{2}$
- tax_totalstringrequired
  Taxes.
  pattern ^-?\d+\.\d{2}$
- totalstringrequired
  Total charged.
  pattern ^-?\d+\.\d{2}$
- refunded_totalstringrequired
  Refunded so far.
  pattern ^-?\d+\.\d{2}$
- discount_codestring | nullrequired
  Discount code used.
- payment_methodstringrequired
  Payment method code.
- payment_method_labelstringrequired
  Payment method as shown.
- line_itemsarray of LineItemrequired
  Lines.
  ShowHide item attributes
  idintegerrequired
  Line item id.
  product_idinteger | nullrequired
  Product (null if deleted).
  variant_idinteger | nullrequired
  Variant (null if deleted).
  namestringrequired
  Product name when ordered.
  variant_titlestring | nullrequired
  Variant title.
  skustring | nullrequired
  SKU.
  kindstringrequired
  Line kind.
  One of:physicaldigitalgift_cardbooking
  quantityintegerrequired
  Quantity.
  unit_pricestringrequired
  Unit price.
  pattern ^-?\d+\.\d{2}$
  discountstringrequired
  Discount on the line.
  pattern ^-?\d+\.\d{2}$
  taxstringrequired
  Tax on the line.
  pattern ^-?\d+\.\d{2}$
  line_totalstringrequired
  unit_price × quantity (before discount).
  pattern ^-?\d+\.\d{2}$
  fulfilled_atstring<date-time> | nullrequired
  When the line shipped.
- fulfillmentstringrequired
  Delivery method.
  One of:shippickupdigitalpos
- shipping_lineobject | nullrequired
  ShowHide child attributes
  titlestringrequired
  Shipping method.
  pricestringrequired
  Its price.
  pattern ^-?\d+\.\d{2}$
- shipping_addressAddress | any | nullrequired
  ShowHide child attributes
  One of the following:
  Address
  first_namestring | null
  First name.
  last_namestring | null
  Last name.
  companystring | null
  Company.
  line1string | null
  Line1.
  line2string | null
  Line2.
  citystring | null
  City.
  regionstring | null
  Region.
  postcodestring | null
  Postcode.
  countrystring | null
  ISO 3166-1 alpha-2 country code.
  phonestring | null
  Phone.
  any | null
- billing_addressAddress | any | nullrequired
  ShowHide child attributes
  One of the following:
  Address
  first_namestring | null
  First name.
  last_namestring | null
  Last name.
  companystring | null
  Company.
  line1string | null
  Line1.
  line2string | null
  Line2.
  citystring | null
  City.
  regionstring | null
  Region.
  postcodestring | null
  Postcode.
  countrystring | null
  ISO 3166-1 alpha-2 country code.
  phonestring | null
  Phone.
  any | null
- trackingobject | nullrequired
  ShowHide child attributes
  companystring | null
  Carrier.
  numberstring | null
  Tracking number.
  urlstring | null
  Tracking URL.
- tagsarray of stringrequired
  Your tags (PATCH /orders/{id}).
- notestring | nullrequired
  Staff note (PATCH /orders/{id}); not shown to the customer.
- customer_notestring | nullrequired
  Note from the customer.
- location_idinteger | nullrequired
  Fulfilling location.
- placed_atstring<date-time> | nullrequired
  Placed.
- paid_atstring<date-time> | nullrequired
  Paid.
- fulfilled_atstring<date-time> | nullrequired
  Shipped.
- delivered_atstring<date-time> | nullrequired
  Delivered.
- cancelled_atstring<date-time> | nullrequired
  Cancelled.
- created_atstring<date-time>required
  Created.
- updated_atstring<date-time>required
  Last changed.
has_morebooleanrequired
More pages after this one.
next_cursorstring | nullrequired
Pass as cursor for the next page; null on the last page.

200 response

{
  "data": [
    {
      "object": "order",
      "id": 5521,
      "number": 1042,
      "name": "#1042",
      "status": "processing",
      "payment_status": "paid",
      "fulfillment_status": "unfulfilled",
      "source": "storefront",
      "test": false,
      "email": "ann@example.com",
      "phone": "+15125550199",
      "customer_id": 880,
      "customer_name": "Ann Lee",
      "currency": "USD",
      "subtotal": "48.00",
      "discount_total": "4.80",
      "shipping_total": "5.00",
      "tax_total": "3.17",
      "total": "51.37",
      "refunded_total": "0.00",
      "discount_code": "WELCOME10",
      "payment_method": "stripe",
      "payment_method_label": "Card",
      "line_items": [
        {
          "id": 9001,
          "product_id": 120,
          "variant_id": 311,
          "name": "Organic cotton tee",
          "variant_title": "Blue / Large",
          "sku": "TEE-BL-L",
          "kind": "physical",
          "quantity": 2,
          "unit_price": "24.00",
          "discount": "4.80",
          "tax": "3.17",
          "line_total": "48.00",
          "fulfilled_at": null
        }
      ],
      "fulfillment": "ship",
      "shipping_line": {
        "title": "Standard",
        "price": "5.00"
      },
      "shipping_address": {
        "first_name": "Ann",
        "last_name": "Lee",
        "company": null,
        "line1": "1 Main St",
        "line2": "Apt 2",
        "city": "Austin",
        "region": "TX",
        "postcode": "73301",
        "country": "US",
        "phone": "+15125550199"
      },
      "billing_address": {
        "first_name": "Ann",
        "last_name": "Lee",
        "company": null,
        "line1": "1 Main St",
        "line2": "Apt 2",
        "city": "Austin",
        "region": "TX",
        "postcode": "73301",
        "country": "US",
        "phone": "+15125550199"
      },
      "tracking": null,
      "tags": [
        "wholesale"
      ],
      "note": "Gift wrap",
      "customer_note": "Please leave at the door.",
      "location_id": 1,
      "placed_at": "2026-11-02T15:00:00Z",
      "paid_at": "2026-11-02T15:00:00Z",
      "fulfilled_at": null,
      "delivered_at": null,
      "cancelled_at": null,
      "created_at": "2026-11-02T15:00:00Z",
      "updated_at": "2026-11-03T09:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Error responses

400invalid_requestMalformed request (e.g. a bad cursor).
401authenticationMissing, invalid, expired or revoked API key.
403permissionThe key lacks the scope, or the store's plan doesn't include the API.
422invalid_requestInvalid parameters; errors lists each field.
429rate_limitedToo many requests.
500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.

Priced by the same engine as checkout (catalogue prices unless given, group prices, discount codes, automatic discounts and taxes); stock is taken at the fulfilling location. Fires order.created (and order.paid when paid).

Required scopes:write_orders

Headers

Name	Type	Description
`Idempotency-Key`	string	Any unique string (e.g. a UUID, up to 255 characters). A retry with the same key and body within 24 hours gets the first response again (Idempotent-Replayed: true); the same key with a different body is a 409 conflict.

Request body

line_itemsarray of objectrequired
Up to 100 lines. Stock is checked and taken (at the fulfilling location).
ShowHide item attributes
- variant_idintegerrequired
  Variant to sell.
- quantityintegerrequired
  Quantity (1–10000).
- pricestring | number | null
  Unit price to charge; leave out to use the catalogue price (group prices and quantity breaks included).
customerobjectrequired
id or email is required.
ShowHide child attributes
- idinteger | null
  An existing customer…
- emailstring<email> | null
  …or an email: found, or created.
- first_namestring | null
  First name (new customers).
- last_namestring | null
  Last name.
- phonestring | null
  Phone.
- accepts_marketingboolean
  Email marketing consent (new customers).
shipping_addressAddressInput | any | null
ShowHide child attributes
One of the following:
1. AddressInput
  first_namestring | null
  First name.
  last_namestring | null
  Last name.
  companystring | null
  Company.
  line1stringrequired
  Line1.
  line2string | null
  Line2.
  citystringrequired
  City.
  regionstring | null
  Region.
  postcodestring | null
  Postcode.
  countrystringrequired
  ISO 3166-1 alpha-2 country code.
  min length 2 · max length 2
  phonestring | null
  Phone.
2. any | null
billing_addressAddressInput | any | null
Defaults to the shipping address.
ShowHide child attributes
One of the following:
1. AddressInput
  first_namestring | null
  First name.
  last_namestring | null
  Last name.
  companystring | null
  Company.
  line1stringrequired
  Line1.
  line2string | null
  Line2.
  citystringrequired
  City.
  regionstring | null
  Region.
  postcodestring | null
  Postcode.
  countrystringrequired
  ISO 3166-1 alpha-2 country code.
  min length 2 · max length 2
  phonestring | null
  Phone.
2. any | null
shipping_lineobject | null
The shipping charged (taxed like checkout shipping).
ShowHide child attributes
- titlestringrequired
  Shown on the order.
- pricestring | numberrequired
payment_statusstring
paid: recorded as paid outside SellOrchard (status processing). pending (default): unpaid (status pending).
One of:paidpending
payment_method_labelstring | null
How it was paid, as shown on the order.
send_receiptboolean
Email the order confirmation to the customer (and the new-order email to the store). Default false.
discount_codestring | null
A discount code to apply (checked like at checkout).
tagsarray of string
Tags.
notestring | null
Staff note.
customer_notestring | null
Customer note.

Example request

curl

curl -X POST "https://api.sellorchard.com/v1/orders" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "line_items": [
    {
      "variant_id": 311,
      "quantity": 2
    },
    {
      "variant_id": 312,
      "quantity": 1,
      "price": "20.00"
    }
  ],
  "customer": {
    "email": "ann@example.com",
    "first_name": "Ann",
    "last_name": "Lee"
  }
}'

Response201An order.

Show response schema

dataOrderrequired
ShowHide child attributes
- objectstringrequired
- idintegerrequired
  Order id.
- numberintegerrequired
  Order number.
- namestringrequired
  Number with the store prefix.
- statusstringrequired
  Order status.
  One of:pendingprocessingon_holdshippedready_for_pickupdeliveredcancelledrefunded
- payment_statusstringrequired
  Payment status.
  One of:unpaidauthorizedpaidpartially_refundedrefundedfailed
- fulfillment_statusstringrequired
  unfulfilled, partial (some lines shipped) or fulfilled.
  One of:unfulfilledpartialfulfilled
- sourcestringrequired
  Where it was placed.
  One of:storefrontpossubscriptionapi
- testbooleanrequired
  A test order (free-trial store).
- emailstring<email> | nullrequired
  Customer email.
- phonestring | nullrequired
  Phone.
- customer_idinteger | nullrequired
  Customer.
- customer_namestring | nullrequired
  Name.
- currencystringrequired
  ISO 4217 currency of every amount on the order.
- subtotalstringrequired
  Lines before discounts.
  pattern ^-?\d+\.\d{2}$
- discount_totalstringrequired
  Discounts.
  pattern ^-?\d+\.\d{2}$
- shipping_totalstringrequired
  Shipping.
  pattern ^-?\d+\.\d{2}$
- tax_totalstringrequired
  Taxes.
  pattern ^-?\d+\.\d{2}$
- totalstringrequired
  Total charged.
  pattern ^-?\d+\.\d{2}$
- refunded_totalstringrequired
  Refunded so far.
  pattern ^-?\d+\.\d{2}$
- discount_codestring | nullrequired
  Discount code used.
- payment_methodstringrequired
  Payment method code.
- payment_method_labelstringrequired
  Payment method as shown.
- line_itemsarray of LineItemrequired
  Lines.
  ShowHide item attributes
  idintegerrequired
  Line item id.
  product_idinteger | nullrequired
  Product (null if deleted).
  variant_idinteger | nullrequired
  Variant (null if deleted).
  namestringrequired
  Product name when ordered.
  variant_titlestring | nullrequired
  Variant title.
  skustring | nullrequired
  SKU.
  kindstringrequired
  Line kind.
  One of:physicaldigitalgift_cardbooking
  quantityintegerrequired
  Quantity.
  unit_pricestringrequired
  Unit price.
  pattern ^-?\d+\.\d{2}$
  discountstringrequired
  Discount on the line.
  pattern ^-?\d+\.\d{2}$
  taxstringrequired
  Tax on the line.
  pattern ^-?\d+\.\d{2}$
  line_totalstringrequired
  unit_price × quantity (before discount).
  pattern ^-?\d+\.\d{2}$
  fulfilled_atstring<date-time> | nullrequired
  When the line shipped.
- fulfillmentstringrequired
  Delivery method.
  One of:shippickupdigitalpos
- shipping_lineobject | nullrequired
  ShowHide child attributes
  titlestringrequired
  Shipping method.
  pricestringrequired
  Its price.
  pattern ^-?\d+\.\d{2}$
- shipping_addressAddress | any | nullrequired
  ShowHide child attributes
  One of the following:
  Address
  first_namestring | null
  First name.
  last_namestring | null
  Last name.
  companystring | null
  Company.
  line1string | null
  Line1.
  line2string | null
  Line2.
  citystring | null
  City.
  regionstring | null
  Region.
  postcodestring | null
  Postcode.
  countrystring | null
  ISO 3166-1 alpha-2 country code.
  phonestring | null
  Phone.
  any | null
- billing_addressAddress | any | nullrequired
  ShowHide child attributes
  One of the following:
  Address
  first_namestring | null
  First name.
  last_namestring | null
  Last name.
  companystring | null
  Company.
  line1string | null
  Line1.
  line2string | null
  Line2.
  citystring | null
  City.
  regionstring | null
  Region.
  postcodestring | null
  Postcode.
  countrystring | null
  ISO 3166-1 alpha-2 country code.
  phonestring | null
  Phone.
  any | null
- trackingobject | nullrequired
  ShowHide child attributes
  companystring | null
  Carrier.
  numberstring | null
  Tracking number.
  urlstring | null
  Tracking URL.
- tagsarray of stringrequired
  Your tags (PATCH /orders/{id}).
- notestring | nullrequired
  Staff note (PATCH /orders/{id}); not shown to the customer.
- customer_notestring | nullrequired
  Note from the customer.
- location_idinteger | nullrequired
  Fulfilling location.
- placed_atstring<date-time> | nullrequired
  Placed.
- paid_atstring<date-time> | nullrequired
  Paid.
- fulfilled_atstring<date-time> | nullrequired
  Shipped.
- delivered_atstring<date-time> | nullrequired
  Delivered.
- cancelled_atstring<date-time> | nullrequired
  Cancelled.
- created_atstring<date-time>required
  Created.
- updated_atstring<date-time>required
  Last changed.

201 response

{
  "data": {
    "object": "order",
    "id": 5521,
    "number": 1042,
    "name": "#1042",
    "status": "processing",
    "payment_status": "paid",
    "fulfillment_status": "unfulfilled",
    "source": "storefront",
    "test": false,
    "email": "ann@example.com",
    "phone": "+15125550199",
    "customer_id": 880,
    "customer_name": "Ann Lee",
    "currency": "USD",
    "subtotal": "48.00",
    "discount_total": "4.80",
    "shipping_total": "5.00",
    "tax_total": "3.17",
    "total": "51.37",
    "refunded_total": "0.00",
    "discount_code": "WELCOME10",
    "payment_method": "stripe",
    "payment_method_label": "Card",
    "line_items": [
      {
        "id": 9001,
        "product_id": 120,
        "variant_id": 311,
        "name": "Organic cotton tee",
        "variant_title": "Blue / Large",
        "sku": "TEE-BL-L",
        "kind": "physical",
        "quantity": 2,
        "unit_price": "24.00",
        "discount": "4.80",
        "tax": "3.17",
        "line_total": "48.00",
        "fulfilled_at": null
      }
    ],
    "fulfillment": "ship",
    "shipping_line": {
      "title": "Standard",
      "price": "5.00"
    },
    "shipping_address": {
      "first_name": "Ann",
      "last_name": "Lee",
      "company": null,
      "line1": "1 Main St",
      "line2": "Apt 2",
      "city": "Austin",
      "region": "TX",
      "postcode": "73301",
      "country": "US",
      "phone": "+15125550199"
    },
    "billing_address": {
      "first_name": "Ann",
      "last_name": "Lee",
      "company": null,
      "line1": "1 Main St",
      "line2": "Apt 2",
      "city": "Austin",
      "region": "TX",
      "postcode": "73301",
      "country": "US",
      "phone": "+15125550199"
    },
    "tracking": null,
    "tags": [
      "wholesale"
    ],
    "note": "Gift wrap",
    "customer_note": "Please leave at the door.",
    "location_id": 1,
    "placed_at": "2026-11-02T15:00:00Z",
    "paid_at": "2026-11-02T15:00:00Z",
    "fulfilled_at": null,
    "delivered_at": null,
    "cancelled_at": null,
    "created_at": "2026-11-02T15:00:00Z",
    "updated_at": "2026-11-03T09:30:00Z"
  }
}

Error responses

401authenticationMissing, invalid, expired or revoked API key.
403permissionThe key lacks the scope, or the store's plan doesn't include the API.
409conflictThe Idempotency-Key was used with a different request, or that request is still running.
422invalid_requestInvalid parameters; errors lists each field.
429rate_limitedToo many requests.
500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.

Get an order

get/orders/{id}

Required scopes:read_orders

Path parameters

Name	Type	Description
`id`required	integer	The object id.

Example request

curl

curl "https://api.sellorchard.com/v1/orders/120" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY"

Response200An order.

Show response schema

dataOrderrequired
ShowHide child attributes
- objectstringrequired
- idintegerrequired
  Order id.
- numberintegerrequired
  Order number.
- namestringrequired
  Number with the store prefix.
- statusstringrequired
  Order status.
  One of:pendingprocessingon_holdshippedready_for_pickupdeliveredcancelledrefunded
- payment_statusstringrequired
  Payment status.
  One of:unpaidauthorizedpaidpartially_refundedrefundedfailed
- fulfillment_statusstringrequired
  unfulfilled, partial (some lines shipped) or fulfilled.
  One of:unfulfilledpartialfulfilled
- sourcestringrequired
  Where it was placed.
  One of:storefrontpossubscriptionapi
- testbooleanrequired
  A test order (free-trial store).
- emailstring<email> | nullrequired
  Customer email.
- phonestring | nullrequired
  Phone.
- customer_idinteger | nullrequired
  Customer.
- customer_namestring | nullrequired
  Name.
- currencystringrequired
  ISO 4217 currency of every amount on the order.
- subtotalstringrequired
  Lines before discounts.
  pattern ^-?\d+\.\d{2}$
- discount_totalstringrequired
  Discounts.
  pattern ^-?\d+\.\d{2}$
- shipping_totalstringrequired
  Shipping.
  pattern ^-?\d+\.\d{2}$
- tax_totalstringrequired
  Taxes.
  pattern ^-?\d+\.\d{2}$
- totalstringrequired
  Total charged.
  pattern ^-?\d+\.\d{2}$
- refunded_totalstringrequired
  Refunded so far.
  pattern ^-?\d+\.\d{2}$
- discount_codestring | nullrequired
  Discount code used.
- payment_methodstringrequired
  Payment method code.
- payment_method_labelstringrequired
  Payment method as shown.
- line_itemsarray of LineItemrequired
  Lines.
  ShowHide item attributes
  idintegerrequired
  Line item id.
  product_idinteger | nullrequired
  Product (null if deleted).
  variant_idinteger | nullrequired
  Variant (null if deleted).
  namestringrequired
  Product name when ordered.
  variant_titlestring | nullrequired
  Variant title.
  skustring | nullrequired
  SKU.
  kindstringrequired
  Line kind.
  One of:physicaldigitalgift_cardbooking
  quantityintegerrequired
  Quantity.
  unit_pricestringrequired
  Unit price.
  pattern ^-?\d+\.\d{2}$
  discountstringrequired
  Discount on the line.
  pattern ^-?\d+\.\d{2}$
  taxstringrequired
  Tax on the line.
  pattern ^-?\d+\.\d{2}$
  line_totalstringrequired
  unit_price × quantity (before discount).
  pattern ^-?\d+\.\d{2}$
  fulfilled_atstring<date-time> | nullrequired
  When the line shipped.
- fulfillmentstringrequired
  Delivery method.
  One of:shippickupdigitalpos
- shipping_lineobject | nullrequired
  ShowHide child attributes
  titlestringrequired
  Shipping method.
  pricestringrequired
  Its price.
  pattern ^-?\d+\.\d{2}$
- shipping_addressAddress | any | nullrequired
  ShowHide child attributes
  One of the following:
  Address
  first_namestring | null
  First name.
  last_namestring | null
  Last name.
  companystring | null
  Company.
  line1string | null
  Line1.
  line2string | null
  Line2.
  citystring | null
  City.
  regionstring | null
  Region.
  postcodestring | null
  Postcode.
  countrystring | null
  ISO 3166-1 alpha-2 country code.
  phonestring | null
  Phone.
  any | null
- billing_addressAddress | any | nullrequired
  ShowHide child attributes
  One of the following:
  Address
  first_namestring | null
  First name.
  last_namestring | null
  Last name.
  companystring | null
  Company.
  line1string | null
  Line1.
  line2string | null
  Line2.
  citystring | null
  City.
  regionstring | null
  Region.
  postcodestring | null
  Postcode.
  countrystring | null
  ISO 3166-1 alpha-2 country code.
  phonestring | null
  Phone.
  any | null
- trackingobject | nullrequired
  ShowHide child attributes
  companystring | null
  Carrier.
  numberstring | null
  Tracking number.
  urlstring | null
  Tracking URL.
- tagsarray of stringrequired
  Your tags (PATCH /orders/{id}).
- notestring | nullrequired
  Staff note (PATCH /orders/{id}); not shown to the customer.
- customer_notestring | nullrequired
  Note from the customer.
- location_idinteger | nullrequired
  Fulfilling location.
- placed_atstring<date-time> | nullrequired
  Placed.
- paid_atstring<date-time> | nullrequired
  Paid.
- fulfilled_atstring<date-time> | nullrequired
  Shipped.
- delivered_atstring<date-time> | nullrequired
  Delivered.
- cancelled_atstring<date-time> | nullrequired
  Cancelled.
- created_atstring<date-time>required
  Created.
- updated_atstring<date-time>required
  Last changed.

200 response

{
  "data": {
    "object": "order",
    "id": 5521,
    "number": 1042,
    "name": "#1042",
    "status": "processing",
    "payment_status": "paid",
    "fulfillment_status": "unfulfilled",
    "source": "storefront",
    "test": false,
    "email": "ann@example.com",
    "phone": "+15125550199",
    "customer_id": 880,
    "customer_name": "Ann Lee",
    "currency": "USD",
    "subtotal": "48.00",
    "discount_total": "4.80",
    "shipping_total": "5.00",
    "tax_total": "3.17",
    "total": "51.37",
    "refunded_total": "0.00",
    "discount_code": "WELCOME10",
    "payment_method": "stripe",
    "payment_method_label": "Card",
    "line_items": [
      {
        "id": 9001,
        "product_id": 120,
        "variant_id": 311,
        "name": "Organic cotton tee",
        "variant_title": "Blue / Large",
        "sku": "TEE-BL-L",
        "kind": "physical",
        "quantity": 2,
        "unit_price": "24.00",
        "discount": "4.80",
        "tax": "3.17",
        "line_total": "48.00",
        "fulfilled_at": null
      }
    ],
    "fulfillment": "ship",
    "shipping_line": {
      "title": "Standard",
      "price": "5.00"
    },
    "shipping_address": {
      "first_name": "Ann",
      "last_name": "Lee",
      "company": null,
      "line1": "1 Main St",
      "line2": "Apt 2",
      "city": "Austin",
      "region": "TX",
      "postcode": "73301",
      "country": "US",
      "phone": "+15125550199"
    },
    "billing_address": {
      "first_name": "Ann",
      "last_name": "Lee",
      "company": null,
      "line1": "1 Main St",
      "line2": "Apt 2",
      "city": "Austin",
      "region": "TX",
      "postcode": "73301",
      "country": "US",
      "phone": "+15125550199"
    },
    "tracking": null,
    "tags": [
      "wholesale"
    ],
    "note": "Gift wrap",
    "customer_note": "Please leave at the door.",
    "location_id": 1,
    "placed_at": "2026-11-02T15:00:00Z",
    "paid_at": "2026-11-02T15:00:00Z",
    "fulfilled_at": null,
    "delivered_at": null,
    "cancelled_at": null,
    "created_at": "2026-11-02T15:00:00Z",
    "updated_at": "2026-11-03T09:30:00Z"
  }
}

Error responses

401authenticationMissing, invalid, expired or revoked API key.
403permissionThe key lacks the scope, or the store's plan doesn't include the API.
404not_foundNo such object in this store.
429rate_limitedToo many requests.
500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.

Update an order's tags and note

patch/orders/{id}

Required scopes:write_orders

Path parameters

Name	Type	Description
`id`required	integer	The object id.

Request body

tagsarray of string
Replaces the tags.
notestring | null
Staff note.

Example request

curl

curl -X PATCH "https://api.sellorchard.com/v1/orders/120" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tags": [
    "vip"
  ],
  "note": "Called the customer."
}'

Response200An order.

Show response schema

dataOrderrequired
ShowHide child attributes
- objectstringrequired
- idintegerrequired
  Order id.
- numberintegerrequired
  Order number.
- namestringrequired
  Number with the store prefix.
- statusstringrequired
  Order status.
  One of:pendingprocessingon_holdshippedready_for_pickupdeliveredcancelledrefunded
- payment_statusstringrequired
  Payment status.
  One of:unpaidauthorizedpaidpartially_refundedrefundedfailed
- fulfillment_statusstringrequired
  unfulfilled, partial (some lines shipped) or fulfilled.
  One of:unfulfilledpartialfulfilled
- sourcestringrequired
  Where it was placed.
  One of:storefrontpossubscriptionapi
- testbooleanrequired
  A test order (free-trial store).
- emailstring<email> | nullrequired
  Customer email.
- phonestring | nullrequired
  Phone.
- customer_idinteger | nullrequired
  Customer.
- customer_namestring | nullrequired
  Name.
- currencystringrequired
  ISO 4217 currency of every amount on the order.
- subtotalstringrequired
  Lines before discounts.
  pattern ^-?\d+\.\d{2}$
- discount_totalstringrequired
  Discounts.
  pattern ^-?\d+\.\d{2}$
- shipping_totalstringrequired
  Shipping.
  pattern ^-?\d+\.\d{2}$
- tax_totalstringrequired
  Taxes.
  pattern ^-?\d+\.\d{2}$
- totalstringrequired
  Total charged.
  pattern ^-?\d+\.\d{2}$
- refunded_totalstringrequired
  Refunded so far.
  pattern ^-?\d+\.\d{2}$
- discount_codestring | nullrequired
  Discount code used.
- payment_methodstringrequired
  Payment method code.
- payment_method_labelstringrequired
  Payment method as shown.
- line_itemsarray of LineItemrequired
  Lines.
  ShowHide item attributes
  idintegerrequired
  Line item id.
  product_idinteger | nullrequired
  Product (null if deleted).
  variant_idinteger | nullrequired
  Variant (null if deleted).
  namestringrequired
  Product name when ordered.
  variant_titlestring | nullrequired
  Variant title.
  skustring | nullrequired
  SKU.
  kindstringrequired
  Line kind.
  One of:physicaldigitalgift_cardbooking
  quantityintegerrequired
  Quantity.
  unit_pricestringrequired
  Unit price.
  pattern ^-?\d+\.\d{2}$
  discountstringrequired
  Discount on the line.
  pattern ^-?\d+\.\d{2}$
  taxstringrequired
  Tax on the line.
  pattern ^-?\d+\.\d{2}$
  line_totalstringrequired
  unit_price × quantity (before discount).
  pattern ^-?\d+\.\d{2}$
  fulfilled_atstring<date-time> | nullrequired
  When the line shipped.
- fulfillmentstringrequired
  Delivery method.
  One of:shippickupdigitalpos
- shipping_lineobject | nullrequired
  ShowHide child attributes
  titlestringrequired
  Shipping method.
  pricestringrequired
  Its price.
  pattern ^-?\d+\.\d{2}$
- shipping_addressAddress | any | nullrequired
  ShowHide child attributes
  One of the following:
  Address
  first_namestring | null
  First name.
  last_namestring | null
  Last name.
  companystring | null
  Company.
  line1string | null
  Line1.
  line2string | null
  Line2.
  citystring | null
  City.
  regionstring | null
  Region.
  postcodestring | null
  Postcode.
  countrystring | null
  ISO 3166-1 alpha-2 country code.
  phonestring | null
  Phone.
  any | null
- billing_addressAddress | any | nullrequired
  ShowHide child attributes
  One of the following:
  Address
  first_namestring | null
  First name.
  last_namestring | null
  Last name.
  companystring | null
  Company.
  line1string | null
  Line1.
  line2string | null
  Line2.
  citystring | null
  City.
  regionstring | null
  Region.
  postcodestring | null
  Postcode.
  countrystring | null
  ISO 3166-1 alpha-2 country code.
  phonestring | null
  Phone.
  any | null
- trackingobject | nullrequired
  ShowHide child attributes
  companystring | null
  Carrier.
  numberstring | null
  Tracking number.
  urlstring | null
  Tracking URL.
- tagsarray of stringrequired
  Your tags (PATCH /orders/{id}).
- notestring | nullrequired
  Staff note (PATCH /orders/{id}); not shown to the customer.
- customer_notestring | nullrequired
  Note from the customer.
- location_idinteger | nullrequired
  Fulfilling location.
- placed_atstring<date-time> | nullrequired
  Placed.
- paid_atstring<date-time> | nullrequired
  Paid.
- fulfilled_atstring<date-time> | nullrequired
  Shipped.
- delivered_atstring<date-time> | nullrequired
  Delivered.
- cancelled_atstring<date-time> | nullrequired
  Cancelled.
- created_atstring<date-time>required
  Created.
- updated_atstring<date-time>required
  Last changed.

200 response

{
  "data": {
    "object": "order",
    "id": 5521,
    "number": 1042,
    "name": "#1042",
    "status": "processing",
    "payment_status": "paid",
    "fulfillment_status": "unfulfilled",
    "source": "storefront",
    "test": false,
    "email": "ann@example.com",
    "phone": "+15125550199",
    "customer_id": 880,
    "customer_name": "Ann Lee",
    "currency": "USD",
    "subtotal": "48.00",
    "discount_total": "4.80",
    "shipping_total": "5.00",
    "tax_total": "3.17",
    "total": "51.37",
    "refunded_total": "0.00",
    "discount_code": "WELCOME10",
    "payment_method": "stripe",
    "payment_method_label": "Card",
    "line_items": [
      {
        "id": 9001,
        "product_id": 120,
        "variant_id": 311,
        "name": "Organic cotton tee",
        "variant_title": "Blue / Large",
        "sku": "TEE-BL-L",
        "kind": "physical",
        "quantity": 2,
        "unit_price": "24.00",
        "discount": "4.80",
        "tax": "3.17",
        "line_total": "48.00",
        "fulfilled_at": null
      }
    ],
    "fulfillment": "ship",
    "shipping_line": {
      "title": "Standard",
      "price": "5.00"
    },
    "shipping_address": {
      "first_name": "Ann",
      "last_name": "Lee",
      "company": null,
      "line1": "1 Main St",
      "line2": "Apt 2",
      "city": "Austin",
      "region": "TX",
      "postcode": "73301",
      "country": "US",
      "phone": "+15125550199"
    },
    "billing_address": {
      "first_name": "Ann",
      "last_name": "Lee",
      "company": null,
      "line1": "1 Main St",
      "line2": "Apt 2",
      "city": "Austin",
      "region": "TX",
      "postcode": "73301",
      "country": "US",
      "phone": "+15125550199"
    },
    "tracking": null,
    "tags": [
      "wholesale"
    ],
    "note": "Gift wrap",
    "customer_note": "Please leave at the door.",
    "location_id": 1,
    "placed_at": "2026-11-02T15:00:00Z",
    "paid_at": "2026-11-02T15:00:00Z",
    "fulfilled_at": null,
    "delivered_at": null,
    "cancelled_at": null,
    "created_at": "2026-11-02T15:00:00Z",
    "updated_at": "2026-11-03T09:30:00Z"
  }
}

Error responses

401authenticationMissing, invalid, expired or revoked API key.
403permissionThe key lacks the scope, or the store's plan doesn't include the API.
404not_foundNo such object in this store.
422invalid_requestInvalid parameters; errors lists each field.
429rate_limitedToo many requests.
500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.

Fulfil an order

post/orders/{id}/fulfillments

Marks lines (or the whole order) shipped with tracking; emails the customer like the admin does. Returns the order. Fires order.fulfilled once everything has shipped.

Required scopes:write_orders

Path parameters

Name	Type	Description
`id`required	integer	The object id.

Headers

Name	Type	Description
`Idempotency-Key`	string	Any unique string (e.g. a UUID, up to 255 characters). A retry with the same key and body within 24 hours gets the first response again (Idempotent-Replayed: true); the same key with a different body is a 409 conflict.

Request body

line_itemsarray of object
Lines that shipped; leave out to fulfil the whole order.
ShowHide item attributes
- idintegerrequired
  Line item id.
- quantityinteger | null
  Ignored: whole lines are fulfilled.
tracking_numberstring | null
Tracking number.
tracking_companystring | null
Carrier.
tracking_urlstring<uri> | null
Tracking URL.
notifyboolean
Email the customer (default true).

Example request

curl

curl -X POST "https://api.sellorchard.com/v1/orders/120/fulfillments" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "tracking_number": "1Z999AA10123456784",
  "tracking_company": "UPS",
  "notify": true
}'

Response201An order.

Show response schema

dataOrderrequired
ShowHide child attributes
- objectstringrequired
- idintegerrequired
  Order id.
- numberintegerrequired
  Order number.
- namestringrequired
  Number with the store prefix.
- statusstringrequired
  Order status.
  One of:pendingprocessingon_holdshippedready_for_pickupdeliveredcancelledrefunded
- payment_statusstringrequired
  Payment status.
  One of:unpaidauthorizedpaidpartially_refundedrefundedfailed
- fulfillment_statusstringrequired
  unfulfilled, partial (some lines shipped) or fulfilled.
  One of:unfulfilledpartialfulfilled
- sourcestringrequired
  Where it was placed.
  One of:storefrontpossubscriptionapi
- testbooleanrequired
  A test order (free-trial store).
- emailstring<email> | nullrequired
  Customer email.
- phonestring | nullrequired
  Phone.
- customer_idinteger | nullrequired
  Customer.
- customer_namestring | nullrequired
  Name.
- currencystringrequired
  ISO 4217 currency of every amount on the order.
- subtotalstringrequired
  Lines before discounts.
  pattern ^-?\d+\.\d{2}$
- discount_totalstringrequired
  Discounts.
  pattern ^-?\d+\.\d{2}$
- shipping_totalstringrequired
  Shipping.
  pattern ^-?\d+\.\d{2}$
- tax_totalstringrequired
  Taxes.
  pattern ^-?\d+\.\d{2}$
- totalstringrequired
  Total charged.
  pattern ^-?\d+\.\d{2}$
- refunded_totalstringrequired
  Refunded so far.
  pattern ^-?\d+\.\d{2}$
- discount_codestring | nullrequired
  Discount code used.
- payment_methodstringrequired
  Payment method code.
- payment_method_labelstringrequired
  Payment method as shown.
- line_itemsarray of LineItemrequired
  Lines.
  ShowHide item attributes
  idintegerrequired
  Line item id.
  product_idinteger | nullrequired
  Product (null if deleted).
  variant_idinteger | nullrequired
  Variant (null if deleted).
  namestringrequired
  Product name when ordered.
  variant_titlestring | nullrequired
  Variant title.
  skustring | nullrequired
  SKU.
  kindstringrequired
  Line kind.
  One of:physicaldigitalgift_cardbooking
  quantityintegerrequired
  Quantity.
  unit_pricestringrequired
  Unit price.
  pattern ^-?\d+\.\d{2}$
  discountstringrequired
  Discount on the line.
  pattern ^-?\d+\.\d{2}$
  taxstringrequired
  Tax on the line.
  pattern ^-?\d+\.\d{2}$
  line_totalstringrequired
  unit_price × quantity (before discount).
  pattern ^-?\d+\.\d{2}$
  fulfilled_atstring<date-time> | nullrequired
  When the line shipped.
- fulfillmentstringrequired
  Delivery method.
  One of:shippickupdigitalpos
- shipping_lineobject | nullrequired
  ShowHide child attributes
  titlestringrequired
  Shipping method.
  pricestringrequired
  Its price.
  pattern ^-?\d+\.\d{2}$
- shipping_addressAddress | any | nullrequired
  ShowHide child attributes
  One of the following:
  Address
  first_namestring | null
  First name.
  last_namestring | null
  Last name.
  companystring | null
  Company.
  line1string | null
  Line1.
  line2string | null
  Line2.
  citystring | null
  City.
  regionstring | null
  Region.
  postcodestring | null
  Postcode.
  countrystring | null
  ISO 3166-1 alpha-2 country code.
  phonestring | null
  Phone.
  any | null
- billing_addressAddress | any | nullrequired
  ShowHide child attributes
  One of the following:
  Address
  first_namestring | null
  First name.
  last_namestring | null
  Last name.
  companystring | null
  Company.
  line1string | null
  Line1.
  line2string | null
  Line2.
  citystring | null
  City.
  regionstring | null
  Region.
  postcodestring | null
  Postcode.
  countrystring | null
  ISO 3166-1 alpha-2 country code.
  phonestring | null
  Phone.
  any | null
- trackingobject | nullrequired
  ShowHide child attributes
  companystring | null
  Carrier.
  numberstring | null
  Tracking number.
  urlstring | null
  Tracking URL.
- tagsarray of stringrequired
  Your tags (PATCH /orders/{id}).
- notestring | nullrequired
  Staff note (PATCH /orders/{id}); not shown to the customer.
- customer_notestring | nullrequired
  Note from the customer.
- location_idinteger | nullrequired
  Fulfilling location.
- placed_atstring<date-time> | nullrequired
  Placed.
- paid_atstring<date-time> | nullrequired
  Paid.
- fulfilled_atstring<date-time> | nullrequired
  Shipped.
- delivered_atstring<date-time> | nullrequired
  Delivered.
- cancelled_atstring<date-time> | nullrequired
  Cancelled.
- created_atstring<date-time>required
  Created.
- updated_atstring<date-time>required
  Last changed.

201 response

{
  "data": {
    "object": "order",
    "id": 5521,
    "number": 1042,
    "name": "#1042",
    "status": "processing",
    "payment_status": "paid",
    "fulfillment_status": "unfulfilled",
    "source": "storefront",
    "test": false,
    "email": "ann@example.com",
    "phone": "+15125550199",
    "customer_id": 880,
    "customer_name": "Ann Lee",
    "currency": "USD",
    "subtotal": "48.00",
    "discount_total": "4.80",
    "shipping_total": "5.00",
    "tax_total": "3.17",
    "total": "51.37",
    "refunded_total": "0.00",
    "discount_code": "WELCOME10",
    "payment_method": "stripe",
    "payment_method_label": "Card",
    "line_items": [
      {
        "id": 9001,
        "product_id": 120,
        "variant_id": 311,
        "name": "Organic cotton tee",
        "variant_title": "Blue / Large",
        "sku": "TEE-BL-L",
        "kind": "physical",
        "quantity": 2,
        "unit_price": "24.00",
        "discount": "4.80",
        "tax": "3.17",
        "line_total": "48.00",
        "fulfilled_at": null
      }
    ],
    "fulfillment": "ship",
    "shipping_line": {
      "title": "Standard",
      "price": "5.00"
    },
    "shipping_address": {
      "first_name": "Ann",
      "last_name": "Lee",
      "company": null,
      "line1": "1 Main St",
      "line2": "Apt 2",
      "city": "Austin",
      "region": "TX",
      "postcode": "73301",
      "country": "US",
      "phone": "+15125550199"
    },
    "billing_address": {
      "first_name": "Ann",
      "last_name": "Lee",
      "company": null,
      "line1": "1 Main St",
      "line2": "Apt 2",
      "city": "Austin",
      "region": "TX",
      "postcode": "73301",
      "country": "US",
      "phone": "+15125550199"
    },
    "tracking": null,
    "tags": [
      "wholesale"
    ],
    "note": "Gift wrap",
    "customer_note": "Please leave at the door.",
    "location_id": 1,
    "placed_at": "2026-11-02T15:00:00Z",
    "paid_at": "2026-11-02T15:00:00Z",
    "fulfilled_at": null,
    "delivered_at": null,
    "cancelled_at": null,
    "created_at": "2026-11-02T15:00:00Z",
    "updated_at": "2026-11-03T09:30:00Z"
  }
}

Error responses

401authenticationMissing, invalid, expired or revoked API key.
403permissionThe key lacks the scope, or the store's plan doesn't include the API.
404not_foundNo such object in this store.
409conflictThe Idempotency-Key was used with a different request, or that request is still running.
422invalid_requestInvalid parameters; errors lists each field.
429rate_limitedToo many requests.
500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.

Cancel an order

post/orders/{id}/cancel

Pending, on-hold, processing and ready-for-pickup orders. Fires order.cancelled (and refund.created / order.refunded with refund).

Required scopes:write_orders

Path parameters

Name	Type	Description
`id`required	integer	The object id.

Headers

Name	Type	Description
`Idempotency-Key`	string	Any unique string (e.g. a UUID, up to 255 characters). A retry with the same key and body within 24 hours gets the first response again (Idempotent-Replayed: true); the same key with a different body is a 409 conflict.

Request body

reasonstring | null
Why (on the order timeline).
restockboolean
Put the items back into stock (default true).
refundboolean
Refund what was paid first (default false).
notifyboolean
Email the customer (default true).

Example request

curl

curl -X POST "https://api.sellorchard.com/v1/orders/120/cancel" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Customer changed their mind",
  "restock": true,
  "refund": true
}'

Response200An order.

Show response schema

dataOrderrequired
ShowHide child attributes
- objectstringrequired
- idintegerrequired
  Order id.
- numberintegerrequired
  Order number.
- namestringrequired
  Number with the store prefix.
- statusstringrequired
  Order status.
  One of:pendingprocessingon_holdshippedready_for_pickupdeliveredcancelledrefunded
- payment_statusstringrequired
  Payment status.
  One of:unpaidauthorizedpaidpartially_refundedrefundedfailed
- fulfillment_statusstringrequired
  unfulfilled, partial (some lines shipped) or fulfilled.
  One of:unfulfilledpartialfulfilled
- sourcestringrequired
  Where it was placed.
  One of:storefrontpossubscriptionapi
- testbooleanrequired
  A test order (free-trial store).
- emailstring<email> | nullrequired
  Customer email.
- phonestring | nullrequired
  Phone.
- customer_idinteger | nullrequired
  Customer.
- customer_namestring | nullrequired
  Name.
- currencystringrequired
  ISO 4217 currency of every amount on the order.
- subtotalstringrequired
  Lines before discounts.
  pattern ^-?\d+\.\d{2}$
- discount_totalstringrequired
  Discounts.
  pattern ^-?\d+\.\d{2}$
- shipping_totalstringrequired
  Shipping.
  pattern ^-?\d+\.\d{2}$
- tax_totalstringrequired
  Taxes.
  pattern ^-?\d+\.\d{2}$
- totalstringrequired
  Total charged.
  pattern ^-?\d+\.\d{2}$
- refunded_totalstringrequired
  Refunded so far.
  pattern ^-?\d+\.\d{2}$
- discount_codestring | nullrequired
  Discount code used.
- payment_methodstringrequired
  Payment method code.
- payment_method_labelstringrequired
  Payment method as shown.
- line_itemsarray of LineItemrequired
  Lines.
  ShowHide item attributes
  idintegerrequired
  Line item id.
  product_idinteger | nullrequired
  Product (null if deleted).
  variant_idinteger | nullrequired
  Variant (null if deleted).
  namestringrequired
  Product name when ordered.
  variant_titlestring | nullrequired
  Variant title.
  skustring | nullrequired
  SKU.
  kindstringrequired
  Line kind.
  One of:physicaldigitalgift_cardbooking
  quantityintegerrequired
  Quantity.
  unit_pricestringrequired
  Unit price.
  pattern ^-?\d+\.\d{2}$
  discountstringrequired
  Discount on the line.
  pattern ^-?\d+\.\d{2}$
  taxstringrequired
  Tax on the line.
  pattern ^-?\d+\.\d{2}$
  line_totalstringrequired
  unit_price × quantity (before discount).
  pattern ^-?\d+\.\d{2}$
  fulfilled_atstring<date-time> | nullrequired
  When the line shipped.
- fulfillmentstringrequired
  Delivery method.
  One of:shippickupdigitalpos
- shipping_lineobject | nullrequired
  ShowHide child attributes
  titlestringrequired
  Shipping method.
  pricestringrequired
  Its price.
  pattern ^-?\d+\.\d{2}$
- shipping_addressAddress | any | nullrequired
  ShowHide child attributes
  One of the following:
  Address
  first_namestring | null
  First name.
  last_namestring | null
  Last name.
  companystring | null
  Company.
  line1string | null
  Line1.
  line2string | null
  Line2.
  citystring | null
  City.
  regionstring | null
  Region.
  postcodestring | null
  Postcode.
  countrystring | null
  ISO 3166-1 alpha-2 country code.
  phonestring | null
  Phone.
  any | null
- billing_addressAddress | any | nullrequired
  ShowHide child attributes
  One of the following:
  Address
  first_namestring | null
  First name.
  last_namestring | null
  Last name.
  companystring | null
  Company.
  line1string | null
  Line1.
  line2string | null
  Line2.
  citystring | null
  City.
  regionstring | null
  Region.
  postcodestring | null
  Postcode.
  countrystring | null
  ISO 3166-1 alpha-2 country code.
  phonestring | null
  Phone.
  any | null
- trackingobject | nullrequired
  ShowHide child attributes
  companystring | null
  Carrier.
  numberstring | null
  Tracking number.
  urlstring | null
  Tracking URL.
- tagsarray of stringrequired
  Your tags (PATCH /orders/{id}).
- notestring | nullrequired
  Staff note (PATCH /orders/{id}); not shown to the customer.
- customer_notestring | nullrequired
  Note from the customer.
- location_idinteger | nullrequired
  Fulfilling location.
- placed_atstring<date-time> | nullrequired
  Placed.
- paid_atstring<date-time> | nullrequired
  Paid.
- fulfilled_atstring<date-time> | nullrequired
  Shipped.
- delivered_atstring<date-time> | nullrequired
  Delivered.
- cancelled_atstring<date-time> | nullrequired
  Cancelled.
- created_atstring<date-time>required
  Created.
- updated_atstring<date-time>required
  Last changed.

200 response

{
  "data": {
    "object": "order",
    "id": 5521,
    "number": 1042,
    "name": "#1042",
    "status": "processing",
    "payment_status": "paid",
    "fulfillment_status": "unfulfilled",
    "source": "storefront",
    "test": false,
    "email": "ann@example.com",
    "phone": "+15125550199",
    "customer_id": 880,
    "customer_name": "Ann Lee",
    "currency": "USD",
    "subtotal": "48.00",
    "discount_total": "4.80",
    "shipping_total": "5.00",
    "tax_total": "3.17",
    "total": "51.37",
    "refunded_total": "0.00",
    "discount_code": "WELCOME10",
    "payment_method": "stripe",
    "payment_method_label": "Card",
    "line_items": [
      {
        "id": 9001,
        "product_id": 120,
        "variant_id": 311,
        "name": "Organic cotton tee",
        "variant_title": "Blue / Large",
        "sku": "TEE-BL-L",
        "kind": "physical",
        "quantity": 2,
        "unit_price": "24.00",
        "discount": "4.80",
        "tax": "3.17",
        "line_total": "48.00",
        "fulfilled_at": null
      }
    ],
    "fulfillment": "ship",
    "shipping_line": {
      "title": "Standard",
      "price": "5.00"
    },
    "shipping_address": {
      "first_name": "Ann",
      "last_name": "Lee",
      "company": null,
      "line1": "1 Main St",
      "line2": "Apt 2",
      "city": "Austin",
      "region": "TX",
      "postcode": "73301",
      "country": "US",
      "phone": "+15125550199"
    },
    "billing_address": {
      "first_name": "Ann",
      "last_name": "Lee",
      "company": null,
      "line1": "1 Main St",
      "line2": "Apt 2",
      "city": "Austin",
      "region": "TX",
      "postcode": "73301",
      "country": "US",
      "phone": "+15125550199"
    },
    "tracking": null,
    "tags": [
      "wholesale"
    ],
    "note": "Gift wrap",
    "customer_note": "Please leave at the door.",
    "location_id": 1,
    "placed_at": "2026-11-02T15:00:00Z",
    "paid_at": "2026-11-02T15:00:00Z",
    "fulfilled_at": null,
    "delivered_at": null,
    "cancelled_at": null,
    "created_at": "2026-11-02T15:00:00Z",
    "updated_at": "2026-11-03T09:30:00Z"
  }
}

Error responses

401authenticationMissing, invalid, expired or revoked API key.
403permissionThe key lacks the scope, or the store's plan doesn't include the API.
404not_foundNo such object in this store.
409conflictThe Idempotency-Key was used with a different request, or that request is still running.
422invalid_requestInvalid parameters; errors lists each field.
429rate_limitedToo many requests.
500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.

Refund an order

post/orders/{id}/refunds

Paid orders only, up to what is left. Fires refund.created and order.refunded.

Required scopes:write_orders

Path parameters

Name	Type	Description
`id`required	integer	The object id.

Headers

Name	Type	Description
`Idempotency-Key`	string	Any unique string (e.g. a UUID, up to 255 characters). A retry with the same key and body within 24 hours gets the first response again (Idempotent-Replayed: true); the same key with a different body is a 409 conflict.

Request body

amountstring | number | null
Amount to refund (required without line_items; overrides their sum).
line_itemsarray of object
Lines refunded: the amount is what was paid for those units.
ShowHide item attributes
- idintegerrequired
  Line item id.
- quantityinteger | null
  Units (default all).
restockboolean
Put the line items back into stock (default false).
notestring | null
Reason.

Example request

curl

curl -X POST "https://api.sellorchard.com/v1/orders/120/refunds" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "line_items": [
    {
      "id": 9001,
      "quantity": 1
    }
  ],
  "restock": true,
  "note": "Damaged in transit"
}'

Response201The refund.

Show response schema

dataRefundrequired
ShowHide child attributes
- objectstringrequired
- idintegerrequired
  Refund id.
- order_idintegerrequired
  Order.
- amountstringrequired
  Refunded.
  pattern ^-?\d+\.\d{2}$
- currencystringrequired
  Order currency.
- notestring | nullrequired
  What was recorded.
- created_atstring<date-time>required
  When.

201 response

{
  "data": {
    "object": "refund",
    "id": 70211,
    "order_id": 5521,
    "amount": "24.00",
    "currency": "USD",
    "note": "Refunded 24.00 USD — Damaged in transit (through the API (API key ERP)).",
    "created_at": "2026-11-03T09:30:00Z"
  }
}

Error responses

401authenticationMissing, invalid, expired or revoked API key.
403permissionThe key lacks the scope, or the store's plan doesn't include the API.
404not_foundNo such object in this store.
409conflictThe Idempotency-Key was used with a different request, or that request is still running.
422invalid_requestInvalid parameters; errors lists each field.
429rate_limitedToo many requests.
500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.

Add a note to an order

post/orders/{id}/notes

Added to the order's timeline in the admin.

Required scopes:write_orders

Path parameters

Name	Type	Description
`id`required	integer	The object id.

Headers

Name	Type	Description
`Idempotency-Key`	string	Any unique string (e.g. a UUID, up to 255 characters). A retry with the same key and body within 24 hours gets the first response again (Idempotent-Replayed: true); the same key with a different body is a 409 conflict.

Request body

messagestringrequired
The note (up to 2000 characters).

Example request

curl

curl -X POST "https://api.sellorchard.com/v1/orders/120/notes" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "Customer called about delivery"
}'

Response201The note.

Show response schema

dataOrderNoterequired
ShowHide child attributes
- objectstringrequired
- idintegerrequired
  Note id.
- order_idintegerrequired
  Order.
- messagestringrequired
  Text.
- created_atstring<date-time>required
  When.

201 response

{
  "data": {
    "object": "order_note",
    "id": 70212,
    "order_id": 5521,
    "message": "Customer called about delivery — via API key ERP",
    "created_at": "2026-11-03T09:30:00Z"
  }
}

Error responses

401authenticationMissing, invalid, expired or revoked API key.
403permissionThe key lacks the scope, or the store's plan doesn't include the API.
404not_foundNo such object in this store.
409conflictThe Idempotency-Key was used with a different request, or that request is still running.
422invalid_requestInvalid parameters; errors lists each field.
429rate_limitedToo many requests.
500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.