Cancel
Cancel a placed order. Cancellation fees may apply depending on how far along the fulfillment process the order is. Always check cancellation_terms from the status response before cancelling, and retrieve valid reason codes from the cancellation-reasons endpoint.
Cancel Order
Include a Bearer token. See Authentication.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| orderId | string | required | Order ID returned from create-order |
| cancellationReasonId | string | required | Reason code from the cancellation-reasons endpoint. Example: "006" |
Request Example
{
"orderId": "019c2f0a2c1d74dba2dec3aa6e9cb2c3",
"cancellationReasonId": "006"
}Response
Returns the full ONDC on_cancel response. The order state is updated to "Cancelled", the fulfillments array is updated with a Cancel-type entry, the quote reflects any applicable cancellation fee (or "0.00" if none), and a cancellation object is included with the reason and cancelling party.
| Field | Type | Description |
|---|---|---|
| context | object | ONDC context block with action: "on_cancel" |
| message.order | object | Full updated order object (see below) |
message.order fields
| Field | Type | Description |
|---|---|---|
| id | string | The order ID |
| state | string | Always "Cancelled" on a successful cancel |
| provider | object | Seller details — id and locations[] |
| items[] | array | Ordered items with fulfillment_id, quantity, and tags |
| billing | object | Billing details (name, address, phone, email) |
| fulfillments[] | array | Updated fulfillment with type: "Cancel" and state.descriptor.code: "Cancelled" |
| quote | object | Updated quote. price.value is "0.00" when no fee applies, or the cancellation fee amount otherwise |
| payment | object | Original payment details |
| cancellation | object | Contains cancelled_by (the party who cancelled) and reason.id (the reason code supplied in the request) |
| created_at | string | ISO 8601 timestamp when the order was originally created |
| updated_at | string | ISO 8601 timestamp of the cancellation |
Response Example
{
"data": {
"dto": {
"context": {
"domain": "ONDC:RET11",
"country": "IND",
"city": "std:080",
"action": "on_cancel",
"core_version": "1.2.0",
"bap_id": "ondc.preprod.highwaydelite.com",
"bap_uri": "https://ondc.preprod.highwaydelite.com/ret11",
"bpp_id": "pramaan.ondc.org/beta/preprod/mock/seller",
"bpp_uri": "https://pramaan.ondc.org/beta/preprod/mock/seller",
"transaction_id": "56a55c3f-8052-4bb6-91d6-47e1a178a0c0",
"message_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"timestamp": "2026-06-01T10:45:00.000Z",
"ttl": "PT30S"
},
"message": {
"order": {
"id": "019bb2ca-a956-71a8-83c1-397bc5a092f9",
"state": "Cancelled",
"provider": {
"id": "pramaan_provider_1",
"locations": [
{ "id": "SSL1" }
]
},
"items": [
{
"id": "id_1cctu3_9_0",
"fulfillment_id": "6c00379b-17ec-42b1-bf36-037a744d2056",
"quantity": { "count": 1 },
"tags": [
{ "code": "type", "list": [{ "code": "type", "value": "item" }] }
]
}
],
"billing": {
"name": "John Doe",
"address": {
"door": "12-34",
"building": "MG Road",
"street": "MG Road",
"locality": "Indiranagar",
"city": "Bengaluru",
"state": "Karnataka",
"country": "IND",
"area_code": "560001"
},
"phone": "9876543210",
"email": "john@example.com"
},
"fulfillments": [
{
"id": "6c00379b-17ec-42b1-bf36-037a744d2056",
"type": "Cancel",
"state": {
"descriptor": { "code": "Cancelled" }
}
}
],
"quote": {
"price": { "currency": "INR", "value": "0.00" },
"breakup": [
{
"@ondc/org/item_id": "id_1cctu3_9_0",
"title": "Double Patty Cheese Burger",
"@ondc/org/title_type": "item",
"price": { "currency": "INR", "value": "0.00" }
}
],
"ttl": "PT6H"
},
"payment": {
"params": {
"currency": "INR",
"amount": "610.00",
"transaction_id": "56a55c3f-8052-4bb6-91d6-47e1a178a0c0"
},
"status": "PAID",
"type": "ON-ORDER",
"collected_by": "BAP"
},
"cancellation": {
"cancelled_by": "com.example.buyerapp",
"reason": { "id": "006" }
},
"created_at": "2026-06-01T10:00:00.000Z",
"updated_at": "2026-06-01T10:45:00.000Z"
}
}
},
"status": "ACK"
}
}Cancellation Fees
The fee applied depends on the fulfillment state at the moment of cancellation. The applicable rules are returned in cancellation_terms from the status response. When a fee applies, the quote.price.value in the on_cancel response reflects the fee amount rather than "0.00".
| Fulfillment State | Typical Fee |
|---|---|
| Pending | 0% |
| Packed | 0% |
| Order-picked-up | 10% |
| Out-for-delivery | 30%–35% |
Always retrieve cancellation_terms from the status endpoint before showing a cancel option. This lets you display the exact fee to the user so there are no surprises at cancellation time.
Related Endpoints
| Endpoint | Purpose |
|---|---|
| Cancellation Reasons | Fetch valid cancellationReasonId values before calling this endpoint |
| Status | Check current fulfillment state and cancellation_terms fees before cancelling |
| Create Order | Source of the orderId used in the request body |