StateSet API Docs

curl -X POST https://api.stateset.com/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"
  }
}

POST

orders

{order_id}

cancel

curl -X POST https://api.stateset.com/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_1a2b3c4d5e6f

Body Parameters

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)

number

Amount to refund. If not specified, full refund is processedExample: 99.99

string

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

The cancelled order object

Show properties

string

Order ID

string

New status: cancelled

string

ISO 8601 timestamp of cancellation

string

Reason for cancellation

object

Refund details if payment was processed

Show properties

string

Refund ID

number

Amount refunded

string

Currency of refund

string

Refund status: pending, succeeded, failed

string

When customer will receive refund

array

List of inventory adjustments made

curl -X POST https://api.stateset.com/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 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

Get started

Platform

StateSet One

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce

StateSet EDI

StateSet Mail

StateSet Voice

StateSet NSR

AI Agents

StateSet Sandbox

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Tools

Cancel Order

Overview

Cancellation Rules

Can Cancel

Cannot Cancel

Request

Path Parameters

Body Parameters

Response

Webhooks

Best Practices

Create Refund

Return Order

Update Order

List Orders

​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