Skip to main content
POST
https://api.stateset.network
/
v1
/
orders
/
{order_id}
/
cancel
curl -X POST https://api.stateset.network/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
  }'

{
  "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
  }
}
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

​
order_id
string
required
The unique identifier of the order to cancelExample: ord_1a2b3c4d5e6f

​
Body Parameters

​
reason
string
required
Reason for cancellationOptions:
  • customer_request - Customer initiated cancellation
  • out_of_stock - Item(s) no longer available
  • pricing_error - Incorrect pricing
  • fraud_suspected - Potential fraudulent order
  • duplicate_order - Duplicate order placed
  • other - Other reason (use notes)
​
refund_amount
number
Amount to refund. If not specified, full refund is processedExample: 99.99
​
notes
string
Additional notes about the cancellationExample: "Customer changed mind about purchase"
​
notify_customer
boolean
default:"true"
Whether to send cancellation email to customer
​
restock_items
boolean
default:"true"
Whether to return items to inventory

​
Response

​
order
object
The cancelled order object
​
refund
object
Refund details if payment was processed
​
inventory_updates
array
List of inventory adjustments made
curl -X POST https://api.stateset.network/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
  }'

{
  "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
  }
}

​
Webhooks

This endpoint triggers the following webhook events:
  • order.cancelled - When order is successfully cancelled
  • refund.created - When refund is initiated
  • inventory.updated - When items are restocked

​
Best Practices

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;
};
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);
};
Always provide clear communication about cancellations:
// Custom cancellation email
await stateset.emails.send({
  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
  }
});

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