Cancel Order

Cancel an order before fulfillment with automatic refund processing

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 cancel

Example: ord_1a2b3c4d5e6f

Body Parameters

reason · string · required

Reason for cancellation

Options:

• 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 processed

Example: 99.99

notes · string

Additional notes about the cancellation

Example: "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

Show properties

id · string

Order ID

status · string

New status: cancelled

cancelled_at · string

ISO 8601 timestamp of cancellation

cancellation_reason · string

Reason for cancellation

refund · object

Refund details if payment was processed

Show properties

id · string

Refund ID

amount · number

Amount refunded

currency · string

Currency of refund

status · string

Refund status: pending, succeeded, failed

estimated_arrival · string

When customer will receive refund

inventory_updates · array

List of inventory adjustments made

cURL

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
  }'

Success Response

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

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

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

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
  }
});

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