API reference/Store
Refund a card-paid order
Try itGives some or all of a card-paid order back to the shopper's card, through your connected Stripe account. Leave out amount_cents for everything still refundable. The answer says the refund was SENT to Stripe; refunded_cents on the order goes up only when Stripe's signed confirmation arrives (usually seconds) — then the shopper is emailed in the business's name, and a full refund (or stop_gift_cards: true) cancels the order's gift cards and download links. Orders paid in person can't be refunded here.
POST
/api/v1/sites/{site_id}/orders/{order_id}/refundAuthentication
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:writeDeletesIdempotency-Key requiredMCP tool: refund_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
amount_centsintegerBody · optional- Leave out to refund everything still refundable.1 to 10000000
reasonstringBody · optional- Your own note; never sent to the shopper.At most 300 characters
stop_gift_cardsbooleanBody · optional- On a PART refund, also cancel the order's gift cards and download links (a full refund always does).
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 POST 'https://websites.workflowcorp.com/api/v1/sites/SITE_ID/orders/ORDER_ID/refund' \
-H "Authorization: Bearer $WEBSITEBUDDY_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"amount_cents":1200,"reason":"One mug arrived chipped"}'{
"site_id": "SITE_ID",
"order_id": "ORDER_ID",
"amount_cents": 1200,
"reason": "One mug arrived chipped"
}{
"type": "object",
"properties": {
"refund_id": {
"type": "string"
},
"amount_cents": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"status": {
"type": "string",
"const": "sent",
"description": "Sent to Stripe; confirmed later by its webhook."
},
"order": {
"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
}
},
"required": [
"refund_id",
"amount_cents",
"status",
"order"
],
"additionalProperties": false
}