curl -X POST https://api.stateset.com/api/v1/orders/ord_1a2b3c4d5e6f/cancel \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"reason": "customer_request",
"notes": "Customer found a better price elsewhere",
"notify_customer": true,
"restock_items": true
}'
const cancellation = await stateset.orders.cancel('ord_1a2b3c4d5e6f', {
reason: 'customer_request',
notes: 'Customer found a better price elsewhere',
notify_customer: true,
restock_items: true
});
console.log('Order cancelled:', cancellation.order.id);
console.log('Refund status:', cancellation.refund.status);
cancellation = stateset.orders.cancel(
'ord_1a2b3c4d5e6f',
reason='customer_request',
notes='Customer found a better price elsewhere',
notify_customer=True,
restock_items=True
)
print(f"Order cancelled: {cancellation.order.id}")
print(f"Refund amount: {cancellation.refund.amount}")
$cancellation = $stateset->orders->cancel('ord_1a2b3c4d5e6f', [
'reason' => 'customer_request',
'notes' => 'Customer found a better price elsewhere',
'notify_customer' => true,
'restock_items' => true
]);
echo "Order status: " . $cancellation->order->status;
{
"order": {
"id": "ord_1a2b3c4d5e6f",
"status": "cancelled",
"amount": 149.99,
"currency": "ssusd",
"cancelled_at": "2024-01-15T10:30:00Z",
"cancellation_reason": "customer_request",
"cancellation_notes": "Customer found a better price elsewhere",
"items": [
{
"id": "item_abc123",
"product_id": "prod_widget_001",
"quantity": 2,
"price": 74.99
}
]
},
"refund": {
"id": "ref_xyz789",
"amount": 149.99,
"currency": "ssusd",
"status": "succeeded",
"payment_method": "original_payment_method",
"estimated_arrival": "2024-01-17T10:30:00Z",
"transaction_hash": "0xabc..."
},
"inventory_updates": [
{
"product_id": "prod_widget_001",
"quantity_returned": 2,
"new_available": 152
}
],
"notifications_sent": {
"customer_email": true,
"admin_alert": true,
"webhook": true
}
}
{
"error": {
"type": "invalid_request_error",
"code": "order_not_cancellable",
"message": "Order cannot be cancelled because it has already been shipped",
"order_status": "shipped",
"shipped_at": "2024-01-14T15:00:00Z"
}
}
Cancel Order
Cancel an order before fulfillment with automatic refund processing
POST
/
api
/
v1
/
orders
/
{order_id}
/
cancel
curl -X POST https://api.stateset.com/api/v1/orders/ord_1a2b3c4d5e6f/cancel \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"reason": "customer_request",
"notes": "Customer found a better price elsewhere",
"notify_customer": true,
"restock_items": true
}'
const cancellation = await stateset.orders.cancel('ord_1a2b3c4d5e6f', {
reason: 'customer_request',
notes: 'Customer found a better price elsewhere',
notify_customer: true,
restock_items: true
});
console.log('Order cancelled:', cancellation.order.id);
console.log('Refund status:', cancellation.refund.status);
cancellation = stateset.orders.cancel(
'ord_1a2b3c4d5e6f',
reason='customer_request',
notes='Customer found a better price elsewhere',
notify_customer=True,
restock_items=True
)
print(f"Order cancelled: {cancellation.order.id}")
print(f"Refund amount: {cancellation.refund.amount}")
$cancellation = $stateset->orders->cancel('ord_1a2b3c4d5e6f', [
'reason' => 'customer_request',
'notes' => 'Customer found a better price elsewhere',
'notify_customer' => true,
'restock_items' => true
]);
echo "Order status: " . $cancellation->order->status;
{
"order": {
"id": "ord_1a2b3c4d5e6f",
"status": "cancelled",
"amount": 149.99,
"currency": "ssusd",
"cancelled_at": "2024-01-15T10:30:00Z",
"cancellation_reason": "customer_request",
"cancellation_notes": "Customer found a better price elsewhere",
"items": [
{
"id": "item_abc123",
"product_id": "prod_widget_001",
"quantity": 2,
"price": 74.99
}
]
},
"refund": {
"id": "ref_xyz789",
"amount": 149.99,
"currency": "ssusd",
"status": "succeeded",
"payment_method": "original_payment_method",
"estimated_arrival": "2024-01-17T10:30:00Z",
"transaction_hash": "0xabc..."
},
"inventory_updates": [
{
"product_id": "prod_widget_001",
"quantity_returned": 2,
"new_available": 152
}
],
"notifications_sent": {
"customer_email": true,
"admin_alert": true,
"webhook": true
}
}
{
"error": {
"type": "invalid_request_error",
"code": "order_not_cancellable",
"message": "Order cannot be cancelled because it has already been shipped",
"order_status": "shipped",
"shipped_at": "2024-01-14T15:00:00Z"
}
}
Orders can only be cancelled if they haven’t been shipped. Once shipped, use the return flow instead.
Overview
The cancel order endpoint allows you to cancel an existing order and automatically process refunds. This is useful for customer-requested cancellations, inventory issues, or fraud prevention.Cancellation Rules
Can Cancel
- Status:
pending,processing,paid - No shipments created
- Within cancellation window
Cannot Cancel
- Status:
shipped,delivered - Partial fulfillment started
- Past cancellation deadline
Request
Path Parameters
string
required
The unique identifier of the order to cancelExample:
ord_1a2b3c4d5e6fBody Parameters
string
required
Reason for cancellationOptions:
customer_request- Customer initiated cancellationout_of_stock- Item(s) no longer availablepricing_error- Incorrect pricingfraud_suspected- Potential fraudulent orderduplicate_order- Duplicate order placedother- Other reason (use notes)
number
Amount to refund. If not specified, full refund is processedExample:
99.99string
Additional notes about the cancellationExample:
"Customer changed mind about purchase"boolean
default:"true"
Whether to send cancellation email to customer
boolean
default:"true"
Whether to return items to inventory
Response
object
object
array
List of inventory adjustments made
Errors
Succeeds with201. Failures return 400, 401, 403, 404, 422 or 429 with an error body, per the platform status-code contract.
curl -X POST https://api.stateset.com/api/v1/orders/ord_1a2b3c4d5e6f/cancel \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"reason": "customer_request",
"notes": "Customer found a better price elsewhere",
"notify_customer": true,
"restock_items": true
}'
const cancellation = await stateset.orders.cancel('ord_1a2b3c4d5e6f', {
reason: 'customer_request',
notes: 'Customer found a better price elsewhere',
notify_customer: true,
restock_items: true
});
console.log('Order cancelled:', cancellation.order.id);
console.log('Refund status:', cancellation.refund.status);
cancellation = stateset.orders.cancel(
'ord_1a2b3c4d5e6f',
reason='customer_request',
notes='Customer found a better price elsewhere',
notify_customer=True,
restock_items=True
)
print(f"Order cancelled: {cancellation.order.id}")
print(f"Refund amount: {cancellation.refund.amount}")
$cancellation = $stateset->orders->cancel('ord_1a2b3c4d5e6f', [
'reason' => 'customer_request',
'notes' => 'Customer found a better price elsewhere',
'notify_customer' => true,
'restock_items' => true
]);
echo "Order status: " . $cancellation->order->status;
{
"order": {
"id": "ord_1a2b3c4d5e6f",
"status": "cancelled",
"amount": 149.99,
"currency": "ssusd",
"cancelled_at": "2024-01-15T10:30:00Z",
"cancellation_reason": "customer_request",
"cancellation_notes": "Customer found a better price elsewhere",
"items": [
{
"id": "item_abc123",
"product_id": "prod_widget_001",
"quantity": 2,
"price": 74.99
}
]
},
"refund": {
"id": "ref_xyz789",
"amount": 149.99,
"currency": "ssusd",
"status": "succeeded",
"payment_method": "original_payment_method",
"estimated_arrival": "2024-01-17T10:30:00Z",
"transaction_hash": "0xabc..."
},
"inventory_updates": [
{
"product_id": "prod_widget_001",
"quantity_returned": 2,
"new_available": 152
}
],
"notifications_sent": {
"customer_email": true,
"admin_alert": true,
"webhook": true
}
}
{
"error": {
"type": "invalid_request_error",
"code": "order_not_cancellable",
"message": "Order cannot be cancelled because it has already been shipped",
"order_status": "shipped",
"shipped_at": "2024-01-14T15:00:00Z"
}
}
Webhooks
This endpoint triggers the following webhook events:order.cancelled- When order is successfully cancelledrefund.created- When refund is initiatedinventory.updated- When items are restocked
Best Practices
Implement Cancellation Windows
Implement Cancellation Windows
Set clear cancellation deadlines based on your fulfillment process:
// Check if order can be cancelled
const canCancel = (order) => {
const hoursSinceOrder = (Date.now() - order.created_at) / (1000 * 60 * 60);
return order.status !== 'shipped' && hoursSinceOrder < 24;
};
Handle Partial Payments
Handle Partial Payments
For orders with multiple payment methods or partial payments:
// Calculate refund for partial payments
const calculateRefund = (order, cancellationFees = 0) => {
const paidAmount = order.payments
.filter(p => p.status === 'succeeded')
.reduce((sum, p) => sum + p.amount, 0);
return Math.max(0, paidAmount - cancellationFees);
};
Customer Communication
Customer Communication
Always provide clear communication about cancellations:
// StateSet does not send customer email for you — trigger your email
// provider (Resend, SendGrid, Postmark, ...) from the cancellation flow
await sendEmail({
to: order.customer.email,
template: 'order_cancelled',
data: {
order_number: order.number,
refund_amount: refund.amount,
refund_timeline: '3-5 business days',
reason: cancellation.reason
}
});
Related Endpoints
Create Refund
Process partial refunds without cancelling
Return Order
Handle returns for delivered orders
Update Order
Modify order details before fulfillment
List Orders
Query orders by status or customer
Last modified on August 31, 2026