API reference/Store
Move an order along
Try itSets an order's state: ready, picked_up (a pickup order), shipped (a shipping order — send carrier and tracking_number, or tracking_url for carrier other), cancelled, or back to new. ready on a PICKUP order emails the shopper "ready to pick up"; shipped emails them "on its way" with the tracking link — each once per order, in the business's name. Sending shipped again with new tracking corrects it without a second email. Cancelling puts counted stock (and any gift card money) back; un-cancelling takes it again. It also marks the order read. picked_up / shipped on an order paid in person also emails its gift cards and download links (once).
PATCH
/api/v1/sites/{site_id}/orders/{order_id}Authentication
An API key as Authorization: Bearer or x-api-key. It needs the store:write scope — add and change products and stock (live at once); move orders along.
store:writeChanges the draft or a recordIdempotency-Key optionalMCP tool: update_site_order
Parameters
Named placeholders go in the path; the rest in a JSON body.
site_idstringPath · required- The site's id.1 to 100 characters
order_idstringPath · required- The order's id.1 to 100 characters
statusstringBody · required- One of: new, ready, picked_up, shipped, cancelled
carrierstringBody · optional- shipped only: usps, ups, fedex, dhl or other (default usps).One of: usps, ups, fedex, dhl, other
tracking_numberstringBody · optional- shipped only: letters and numbers (spaces and dashes are fine).At most 60 characters
tracking_urlstringBody · optional- shipped with carrier other only: your own https tracking link.At most 500 characters
Response
200 with JSON on success (schema on the right). Errors use the standard envelope; a retry with the same Idempotency-Key gets the first answer back (how retries work).
curl -X PATCH 'https://websites.workflowcorp.com/api/v1/sites/SITE_ID/orders/ORDER_ID' \
-H "Authorization: Bearer $WEBSITEBUDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"ready"}'{
"site_id": "SITE_ID",
"order_id": "ORDER_ID",
"status": "ready"
}{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"number": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "The site's order number (#1001…)."
},
"status": {
"type": "string",
"enum": [
"new",
"ready",
"picked_up",
"shipped",
"cancelled"
],
"description": "new → ready → picked_up (pickup) or shipped (shipping), or cancelled. A shipping order marked done before shipped existed reads picked_up."
},
"customer": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"email": {
"type": "string"
},
"phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name",
"email",
"phone"
],
"additionalProperties": false
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"subtotal_cents": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"discount_cents": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Taken off by a discount code."
},
"shipping_cents": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"tax_cents": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"total_cents": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "What the shopper pays: subtotal − discount + shipping + tax."
},
"coupon_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"gift_card": {
"anyOf": [
{
"type": "object",
"properties": {
"code": {
"type": "string"
},
"cents": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"code",
"cents"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "A gift card that paid part (or all) of it; total_cents is what was left to pay after it."
},
"fulfilment": {
"type": "string",
"enum": [
"pickup",
"shipping",
"digital"
],
"description": "digital = only gift cards / downloads, emailed once paid."
},
"ship_to": {
"anyOf": [
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"line1": {
"type": "string"
},
"line2": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"type": "string"
},
"region": {
"type": "string"
},
"postal": {
"type": "string"
},
"country": {
"type": "string"
}
},
"required": [
"name",
"line1",
"line2",
"city",
"region",
"postal",
"country"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "The shipping address; null for pickup."
},
"payment": {
"type": "string",
"enum": [
"pickup",
"card",
"gift_card"
],
"description": "pickup = pays in person; card = paid online through your connected Stripe account; gift_card = a gift card paid all of it."
},
"paid": {
"type": "boolean",
"description": "Card and gift card orders: the payment came through. Pickup orders are paid at the counter, so always false here."
},
"digital_sent": {
"type": "boolean",
"description": "Its gift cards and download links have been emailed (after payment)."
},
"paid_cents": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"refunded_cents": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Given back to the shopper's card — only once Stripe has confirmed it (refund_site_order)."
},
"shipment": {
"anyOf": [
{
"type": "object",
"properties": {
"shipped_at": {
"type": "string"
},
"carrier": {
"type": "string",
"enum": [
"usps",
"ups",
"fedex",
"dhl",
"other"
]
},
"tracking_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tracking_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Where the shopper follows it: the carrier's page for the number, or your own link for carrier other."
}
},
"required": [
"shipped_at",
"carrier",
"tracking_number",
"tracking_url"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Set once a shipping order is marked shipped; null otherwise."
},
"shopper_emailed": {
"type": "object",
"properties": {
"ready_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"shipped_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"ready_at",
"shipped_at"
],
"additionalProperties": false,
"description": "When the shopper got the \"ready to pick up\" / \"on its way\" email (once each)."
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"product": {
"type": "string",
"description": "The product's name when ordered (a snapshot)."
},
"option": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"product_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "null when the product or option was deleted since."
},
"option_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"unit_cents": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"quantity": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"kind": {
"type": "string",
"enum": [
"physical",
"gift_card",
"download"
]
}
},
"required": [
"product",
"option",
"product_id",
"option_id",
"unit_cents",
"quantity",
"kind"
],
"additionalProperties": false
}
},
"read": {
"type": "boolean",
"description": "Someone has opened or handled it in the console."
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"required": [
"id",
"number",
"status",
"customer",
"note",
"subtotal_cents",
"discount_cents",
"shipping_cents",
"tax_cents",
"total_cents",
"coupon_code",
"gift_card",
"fulfilment",
"ship_to",
"payment",
"paid",
"digital_sent",
"paid_cents",
"refunded_cents",
"shipment",
"shopper_emailed",
"items",
"read",
"created_at",
"updated_at"
],
"additionalProperties": false
}