API reference

Customers

Customers and their orders.

On this page

List customers
Create a customer
Get a customer
Update a customer
List a customer's orders

List customers

get/customers

Required scopes:read_customers

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.
`email`	string	Exact email.
`accepts_marketing`	boolean	Marketing consent.

Example request

curl

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

Response200Customers, newest first.

Show response schema

dataarray of Customerrequired
ShowHide item attributes
- objectstringrequired
- idintegerrequired
  Id.
- emailstring<email>required
  Email (unique in the store).
- first_namestring | nullrequired
  First name.
- last_namestring | nullrequired
  Last name.
- phonestring | nullrequired
  Phone.
- companystring | nullrequired
  Company.
- accepts_marketingbooleanrequired
  Email marketing consent.
- notestring | nullrequired
  Staff note.
- has_accountbooleanrequired
  Has a storefront account.
- is_blockedbooleanrequired
  Blocked from ordering.
- orders_countintegerrequired
  Orders (not cancelled or test).
- total_spentstringrequired
  Paid, less refunds.
  pattern ^-?\d+\.\d{2}$
- currencystringrequired
  Store currency.
- addressesarray of CustomerAddressrequired
  Saved addresses.
  ShowHide item attributes
  idintegerrequired
  Address id.
  is_defaultbooleanrequired
  Default 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.
- last_order_atstring<date-time> | nullrequired
  Last order.
- 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": "customer",
      "id": 880,
      "email": "ann@example.com",
      "first_name": "Ann",
      "last_name": "Lee",
      "phone": "+15125550199",
      "company": null,
      "accepts_marketing": true,
      "note": null,
      "has_account": true,
      "is_blocked": false,
      "orders_count": 3,
      "total_spent": "154.11",
      "currency": "USD",
      "addresses": [
        {
          "id": 61,
          "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",
          "is_default": true
        }
      ],
      "last_order_at": "2026-11-02T15:00:00Z",
      "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.

Create a customer

post/customers

Fires customer.created.

Required scopes:write_customers

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

emailstring<email>
Email (required on create; unique).
first_namestring | null
First name.
last_namestring | null
Last name.
phonestring | null
Phone.
companystring | null
Company.
notestring | null
Staff note.
accepts_marketingboolean
Email marketing consent.
addressesarray of object
Replaces the saved addresses when sent.
ShowHide item attributes
- is_defaultboolean
  Default address (else the first).
- 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.

Example request

curl

curl -X POST "https://api.sellorchard.com/v1/customers" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ann@example.com",
  "first_name": "Ann",
  "last_name": "Lee",
  "accepts_marketing": true,
  "addresses": [
    {
      "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"
    }
  ]
}'

Response201A customer.

Show response schema

dataCustomerrequired
ShowHide child attributes
- objectstringrequired
- idintegerrequired
  Id.
- emailstring<email>required
  Email (unique in the store).
- first_namestring | nullrequired
  First name.
- last_namestring | nullrequired
  Last name.
- phonestring | nullrequired
  Phone.
- companystring | nullrequired
  Company.
- accepts_marketingbooleanrequired
  Email marketing consent.
- notestring | nullrequired
  Staff note.
- has_accountbooleanrequired
  Has a storefront account.
- is_blockedbooleanrequired
  Blocked from ordering.
- orders_countintegerrequired
  Orders (not cancelled or test).
- total_spentstringrequired
  Paid, less refunds.
  pattern ^-?\d+\.\d{2}$
- currencystringrequired
  Store currency.
- addressesarray of CustomerAddressrequired
  Saved addresses.
  ShowHide item attributes
  idintegerrequired
  Address id.
  is_defaultbooleanrequired
  Default 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.
- last_order_atstring<date-time> | nullrequired
  Last order.
- created_atstring<date-time>required
  Created.
- updated_atstring<date-time>required
  Last changed.

201 response

{
  "data": {
    "object": "customer",
    "id": 880,
    "email": "ann@example.com",
    "first_name": "Ann",
    "last_name": "Lee",
    "phone": "+15125550199",
    "company": null,
    "accepts_marketing": true,
    "note": null,
    "has_account": true,
    "is_blocked": false,
    "orders_count": 3,
    "total_spent": "154.11",
    "currency": "USD",
    "addresses": [
      {
        "id": 61,
        "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",
        "is_default": true
      }
    ],
    "last_order_at": "2026-11-02T15:00:00Z",
    "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 a customer

get/customers/{id}

Required scopes:read_customers

Path parameters

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

Example request

curl

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

Response200A customer.

Show response schema

dataCustomerrequired
ShowHide child attributes
- objectstringrequired
- idintegerrequired
  Id.
- emailstring<email>required
  Email (unique in the store).
- first_namestring | nullrequired
  First name.
- last_namestring | nullrequired
  Last name.
- phonestring | nullrequired
  Phone.
- companystring | nullrequired
  Company.
- accepts_marketingbooleanrequired
  Email marketing consent.
- notestring | nullrequired
  Staff note.
- has_accountbooleanrequired
  Has a storefront account.
- is_blockedbooleanrequired
  Blocked from ordering.
- orders_countintegerrequired
  Orders (not cancelled or test).
- total_spentstringrequired
  Paid, less refunds.
  pattern ^-?\d+\.\d{2}$
- currencystringrequired
  Store currency.
- addressesarray of CustomerAddressrequired
  Saved addresses.
  ShowHide item attributes
  idintegerrequired
  Address id.
  is_defaultbooleanrequired
  Default 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.
- last_order_atstring<date-time> | nullrequired
  Last order.
- created_atstring<date-time>required
  Created.
- updated_atstring<date-time>required
  Last changed.

200 response

{
  "data": {
    "object": "customer",
    "id": 880,
    "email": "ann@example.com",
    "first_name": "Ann",
    "last_name": "Lee",
    "phone": "+15125550199",
    "company": null,
    "accepts_marketing": true,
    "note": null,
    "has_account": true,
    "is_blocked": false,
    "orders_count": 3,
    "total_spent": "154.11",
    "currency": "USD",
    "addresses": [
      {
        "id": 61,
        "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",
        "is_default": true
      }
    ],
    "last_order_at": "2026-11-02T15:00:00Z",
    "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 a customer

patch/customers/{id}

Only the fields sent change; addresses replaces the saved addresses. Fires customer.updated.

Required scopes:write_customers

Path parameters

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

Request body

emailstring<email>
Email (required on create; unique).
first_namestring | null
First name.
last_namestring | null
Last name.
phonestring | null
Phone.
companystring | null
Company.
notestring | null
Staff note.
accepts_marketingboolean
Email marketing consent.
addressesarray of object
Replaces the saved addresses when sent.
ShowHide item attributes
- is_defaultboolean
  Default address (else the first).
- 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.

Example request

curl

curl -X PATCH "https://api.sellorchard.com/v1/customers/120" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ann@example.com",
  "first_name": "Ann",
  "last_name": "Lee",
  "accepts_marketing": true,
  "addresses": [
    {
      "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"
    }
  ]
}'

Response200A customer.

Show response schema

dataCustomerrequired
ShowHide child attributes
- objectstringrequired
- idintegerrequired
  Id.
- emailstring<email>required
  Email (unique in the store).
- first_namestring | nullrequired
  First name.
- last_namestring | nullrequired
  Last name.
- phonestring | nullrequired
  Phone.
- companystring | nullrequired
  Company.
- accepts_marketingbooleanrequired
  Email marketing consent.
- notestring | nullrequired
  Staff note.
- has_accountbooleanrequired
  Has a storefront account.
- is_blockedbooleanrequired
  Blocked from ordering.
- orders_countintegerrequired
  Orders (not cancelled or test).
- total_spentstringrequired
  Paid, less refunds.
  pattern ^-?\d+\.\d{2}$
- currencystringrequired
  Store currency.
- addressesarray of CustomerAddressrequired
  Saved addresses.
  ShowHide item attributes
  idintegerrequired
  Address id.
  is_defaultbooleanrequired
  Default 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.
- last_order_atstring<date-time> | nullrequired
  Last order.
- created_atstring<date-time>required
  Created.
- updated_atstring<date-time>required
  Last changed.

200 response

{
  "data": {
    "object": "customer",
    "id": 880,
    "email": "ann@example.com",
    "first_name": "Ann",
    "last_name": "Lee",
    "phone": "+15125550199",
    "company": null,
    "accepts_marketing": true,
    "note": null,
    "has_account": true,
    "is_blocked": false,
    "orders_count": 3,
    "total_spent": "154.11",
    "currency": "USD",
    "addresses": [
      {
        "id": 61,
        "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",
        "is_default": true
      }
    ],
    "last_order_at": "2026-11-02T15:00:00Z",
    "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.

List a customer's orders

get/customers/{id}/orders

Required scopes:read_customersread_orders

Path parameters

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

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.

Example request

curl

curl "https://api.sellorchard.com/v1/customers/120/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.
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.