Cancel Order - StateSet API Docs

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

POST

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

Show properties

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

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

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

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

Fulfill Order Return Order

StateSet Commerce

​Overview

​Cancellation Rules

Can Cancel

Cannot Cancel

​Request

​Path Parameters

​Body Parameters

​Response

​Webhooks

​Best Practices

​Related Endpoints

Create Refund

Return Order

Update Order

List Orders

Overview

Cancellation Rules

Request

Path Parameters

Body Parameters

Response

Webhooks

Best Practices

Related Endpoints