API reference/Store
List a site's orders
Try itOrders visitors placed in the site's store, newest first, with the customer, lines and payment. Filter by status.
GET
/api/v1/sites/{site_id}/ordersAuthentication
An API key as Authorization: Bearer or x-api-key. It needs the store:read scope — read store products, stock and orders.
store:readRead onlyMCP tool: list_site_orders
Parameters
Named placeholders go in the path; the rest in the query string.
site_idstringPath · required- The site's id.1 to 100 characters
statusstringQuery · optional- Only orders in this state.One of: new, ready, picked_up, shipped, cancelled
unreadstringQuery · optional- true = only orders nobody has opened yet.One of: 0, 1, true, false
limitintegerQuery · optional- How many to return (1–100).1 to 100Default
50 cursorstringQuery · optional- next_cursor from the previous page.1 to 100 characters
Response
200 with JSON on success (schema on the right). Errors use the standard envelope.
curl -X GET 'https://websites.workflowcorp.com/api/v1/sites/SITE_ID/orders?status=new&limit=20' \
-H "Authorization: Bearer $WEBSITEBUDDY_API_KEY"{
"site_id": "SITE_ID",
"status": "new",
"limit": 20
}{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"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
}
},
"has_more": {
"type": "boolean"
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"data",
"has_more",
"next_cursor"
],
"additionalProperties": false
}