Cancel Order

Cancels an order and all its associated fulfillment orders.

Status Requirements

Orders can only be cancelled when in one of these statuses:

  • ✅ open - Order has been created but not yet allocated
  • ✅ allocated - Order is fully allocated to fulfillment locations
  • ✅ partially_allocated - Order is partially allocated

Orders cannot be cancelled when in these statuses:

  • ❌ partially_fulfilled - Some items have already been shipped
  • ❌ fulfilled - All items have been shipped
  • ❌ closed - Order has been closed
  • ❌ cancelled - Order is already cancelled

Cancellation Effects

When an order is successfully cancelled:

  • All line items quantities are set to 0 with removed quantities recorded
  • All fulfillment order line items are marked as cancelled
  • Reserved inventory is released back to stock
  • Order status is updated to cancelled
  • Webhooks are triggered to notify your systems

Cancellation Reason

You must provide a cancellation_reason which is one of the predefined enum values:

  • CUSTOMER_CANCELLATION - Customer requested cancellation
  • AUTO_ALLOCATION_FAILED - Automatic fulfillment allocation failed
  • INVENTORY_OUT_OF_STOCK - Items are out of stock
  • STAFF_ERROR - Staff made an error
  • PAYMENT_ISSUE - Payment problem occurred
  • OTHER - Other reason
SecurityOAuth2-Production or OAuth2-Demo
Request
path Parameters
reference
required
string

The order reference (order_id or partner_order_reference based on the key parameter).

query Parameters
key
string
Default: "order_id"

Specifies which reference type is being used:

  • order_id: Carriyo's unique order identifier (default)
  • partner_order_reference: Your system's order reference
Enum: "order_id" "partner_order_reference"
header Parameters
x-api-key
required
string

Your Carriyo API key for authentication.

tenant-id
required
string

Your unique tenant identifier in Carriyo.

Content-Type
string
Default: application/json
Request Body schema: application/json
optional
cancellation_reason
string (Cancellation Reason)

The reason for cancellation. Must be one of the following values:

  • CUSTOMER_CANCELLATION - Customer requested cancellation
  • AUTO_ALLOCATION_FAILED - Automatic fulfillment allocation failed
  • INVENTORY_OUT_OF_STOCK - Items are out of stock
  • STAFF_ERROR - Staff made an error
  • PAYMENT_ISSUE - Payment problem occurred
  • OTHER - Other reason
Enum: "CUSTOMER_CANCELLATION" "AUTO_ALLOCATION_FAILED" "INVENTORY_OUT_OF_STOCK" "STAFF_ERROR" "PAYMENT_ISSUE" "OTHER"
Responses
200

Order cancelled successfully.

400

Order cannot be cancelled.

404

Order not found.

post/orders/{reference}/cancel
Request samples
application/json
{
  • "cancellation_reason": "CUSTOMER_CANCELLATION"
}
Response samples
application/json
{
  • "tenant": "string",
  • "order_id": "string",
  • "merchant": "string",
  • "partner_order_reference": "string",
  • "language": "string",
  • "order_date": "2019-08-24T14:15:22Z",
  • "sales_channel": "string",
  • "creation_source": {
    },
  • "update_source": {
    },
  • "carriyo_metadata": [
    ],
  • "status": "open",
  • "auto_allocation_failed": true,
  • "cancellation_reason": "CUSTOMER_CANCELLATION",
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "customer": {
    },
  • "payment": {
    },
  • "redacted": true,
  • "taxes_included": true,
  • "duties_included": true,
  • "discount_applications": [
    ],
  • "line_items": [
    ],
  • "fulfillment_orders": [
    ],
  • "shipping_lines": [
    ],
  • "error_details": [
    ],
  • "creation_date": "2019-08-24T14:15:22Z",
  • "update_date": "2019-08-24T14:15:22Z"
}