# Cancel order by ID

This endpoint allows canceling an order and its transactions using the reference ID obtained in the response to its creation. Only an order with `status=action_required` or `status=created` can be canceled. In case of success, the request will return a response with status 200.

**POST** `/v1/orders/{order_id}/cancel`

## Request parameters

### Header

- `X-Idempotency-Key` (string, required)
  This feature allows you to safely retry requests without the risk of accidentally performing the same action more than once. This is useful for avoiding errors, such as creating two identical payments. To ensure that each request is unique, it's important to use an exclusive value in the header of your request. We suggest using a UUID V4 or random strings. The header accepts values between 1 and 128 characters.

### Path

- `order_id` (string, required)
  ID of the order that is being canceled. This value is returned in the response to the request made to the endpoint [POST /v1/orders](/developers/en/reference/online-payments/checkout-api/create-order/post).

## Response parameters

- `id` (string, optional)
  Identifier of the order created in the request, automatically generated by Mercado Pago.

- `processing_mode` (string, optional)
  Order processing mode
Possible enum values:

  - `manual`
  Order's processing will be made manually. It is the processing mode used for the `manual` option, as it sets the processing to be made afterwards, by using the endpoint [POST /v1/orders/{order_id}/process](/developers/en/reference/online-payments/checkout-api/process-order/post).

  - `automatic`
  Order's processing will be made instantly. It is the capture mode used for the `automatic` option.

- `external_reference` (string, optional)
  It is an external reference of the order. It can be, for example, a hashcode from the Central Bank, functioning as an identifier of the transaction origin. This field must have a maximum of 64 characters and can only be numbers, letters, hyphens (-) and underscores (_). Special characters ([ ], (), '', @) are not allowed. Optional for card, Rapipago, and Pago Fácil payments.

- `total_amount` (string, optional)
  Total amount to be paid.

- `integration_data` (object, optional)
  Additional information that can be used to integrate with other systems, such as the identifier of the order in the integrator's system.

  - `integration_data.application_id` (string, optional)
  Identifier of the Mercado Pago application that created the order.

  - `integration_data.integrator_id` (string, optional)
  Identifier of the integrator in Mercado Pago. It is the unique identifier of the integrator in Mercado Pago's systems.

  - `integration_data.platform_id` (string, optional)
  Identifier of the platform in Mercado Pago. It is the unique identifier of the platform in Mercado Pago's systems.

  - `integration_data.sponsor` (object, optional)
  Identifier of the sponsor in Mercado Pago. It is the unique identifier of the sponsor in Mercado Pago's systems.

  - `integration_data.sponsor.id` (string, optional)
  Identifier of the sponsor in Mercado Pago. It is the unique identifier of the sponsor in Mercado Pago's systems.

- `user_id` (string, optional)
  Identifier of the user to which the Mercado Pago application that created the order belongs. It is the person that will receive the payment.

- `created_date` (string, optional)
  Order's creation date, in `yyyy-MM-ddTHH:mm:ss.sssZ` format.

- `last_updated_date` (string, optional)
  Order's last update date, in `yyyy-MM-ddTHH:mm:ss.sssZ` format.

- `country_code` (string, optional)
  Identifier of the site (country) to which the Mercado Pago application that created the order belongs.

- `type` (string, optional)
  Order type, associated with the Mercado Pago solution for which it is created. For online card payments, the only possible value is `online`.
Possible enum values:

  - `online`
  Value associated with the creation of Orders for online payments.

- `status` (string, optional)
  Current status of the order.
Possible enum values:

  - `canceled`
  The order has been canceled successfully.

- `status_detail` (string, optional)
  Details about payment status.
Possible enum values:

  - `canceled_transaction`
  The order has been canceled successfully.

- `capture_mode` (string, optional)
  Order capture mode.
Possible enum values:

  - `manual`
  Order's capture will be made manually. It allows the reservation of the transaction value in the payer's card, so the capture can be made afterwards, by using the endpoint [POST /v1/orders/{order_id}/capture](/developers/en/reference/online-payments/checkout-api/capture-order/post).

  - `automatic`
  Order's capture will be made automatically. Authorize and capture values at the same time.

  - `automatic_async`
  The order can be processed asynchronously. The order may remain in `status=processing` awaiting asynchronous update and the final status will be updated later through [webhooks](/developers/en/docs/checkout-api-orders/notifications) or queries.

- `transactions` (object, optional)
  Contains information about the transactions associated with the order.

  - `transactions.payments` (array, optional)
  Contains information about the payment associated with the order.

  - `transactions.payments[].id` (string, optional)
  Identifier of the payment transaction created in the request, automatically generated by Mercado Pago.

  - `transactions.payments[].amount` (string, optional)
  Transaction amount.

  - `transactions.payments[].reference_id` (string, optional)
  Reference ID of the transaction.

  - `transactions.payments[].status` (string, optional)
  Payment status.
Possible enum values:

  - `canceled`
  The payment has been canceled and cannot be processed.

  - `transactions.payments[].status_detail` (string, optional)
  Details about payment status.
Possible enum values:

  - `canceled_transaction`
  The transaction has been canceled.

  - `transactions.payments[].expiration_time` (string, optional)
  Transaction expiration date.

  - `transactions.payments[].payment_method` (object, optional)
  Information about the payment method used in the transaction.

  - `transactions.payments[].payment_method.id` (string, optional)
  Identifier of the payment method selected to make the payment. If it's a card payment, it will show the brand.
Possible enum values:

  - `visa`
  Visa credit card.

  - `master`
  Master credit card.

  - `debmaster`
  Master debit card.

  - `debvisa`
  Visa debit card.

  - `rapipago`
  "Rapipago" payment.

  - `pagofacil`
  "Pago fácil" payment.

  - `transactions.payments[].payment_method.type` (string, optional)
  Type of payment method selected to make the payment.
Possible enum values:

  - `credit_card`
  Credit card.

  - `debit_card`
  Debit card.

  - `ticket`
  Cash payment.

  - `transactions.payments[].payment_method.token` (string, optional)
  Token that identifies the card and contains its data securely. Only required for card payments. It has a minimum length of 32 characters, and a maximum length of 33. If you don't know how to generate it, go to the [card payment configuration](/developers/en/docs/checkout-api-orders/payment-integration/websites/cards).

  - `transactions.payments[].payment_method.installments` (integer, optional)
  Number of installments selected.

  - `transactions.payments[].payment_method.installment_amount` (string, optional)
  Amount per installment. The field can contain two decimal places or none.

  - `transactions.payments[].payment_method.statement_descriptor` (string, optional)
  Description used to identify the charge on the buyer's payment method statement. The field accepts up to 50 characters, but on credit card statements, approximately 10 characters may be displayed depending on the card issuer.

- `description` (string, optional)
  Description of the purchased product or service , the reason for the payment order, or the description of a product in the marketplace.

- `items` (array, optional)
  Information about the list of items to be paid.

  - `items[].title` (string, optional)
  Item name. The character limit is 150.

  - `items[].unit_price` (string, optional)
  Unit price of the purchased item. This field must have a maximum of 18 characters.

  - `items[].quantity` (Integer, optional)
  Purchased items quantity.

  - `items[].description` (string, optional)
  Purchased item description. The character limit is 100.

  - `items[].external_code` (string, optional)
  Item External code.

  - `items[].picture_url` (string, optional)
  Image URL corresponding to the item.

  - `items[].category_id` (string, optional)
  Item category ID.

  - `items[].type` (string, optional)
  Item type.

  - `items[].warranty` (boolean, optional)
  If the item has a warranty.

  - `items[].event_date` (string, optional)
  Event date.

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | invalid_path_param | The `order_id` provided in the request path is not correct. Please confirm it and provide a valid ID to try again. |
| 400 | empty_required_header | The `X-Idempotency-Key` header is required and was not sent. Make the request again including it. |
| 400 | invalid_idempotency_key_length | The value sent in the `X-Idempotency-Key` header exceeded the allowed size. The header accepts values between 1 and 128 characters. |
| 401 | 401 | The value sent as Access Token is incorrect. Please check and try again with the correct value. |
| 401 | invalid_credentials | There is no support for test credentials. Use test users with production credentials for the sandbox environment and your production credentials for the production environment. |
| 403 | forbidden | The application does not have permission to access this resource. Please check that the Access Token used has the necessary permissions and scopes for this operation. |
| 403 | PA_UNAUTHORIZED_RESULT_FROM_POLICIES | The account is blocked and its API keys have been revoked. At least one policy evaluated by the Policy Agent returned an `UNAUTHORIZED` result. |
| 404 | order_not_found | Order not found. Please check if you provided the correct `order_id`. |
| 409 | cannot_cancel_order | The status of the order does not allow its cancelation. Only orders with `status=action_required` or `status=created` can be canceled. |
| 409 | order_already_canceled | The order has already been canceled. |
| 409 | idempotency_key_already_used | The value sent as the idempotency header (`X-Idempotency-Key`) has already been used. Please try the request again sending a new value. |
| 429 | too_many_requests | Client ID blocked by the gateway because the request limit for the ID in question was reached. Read the `Retry-After` header from the response and wait the indicated number of seconds before retrying. For greater resilience, implement exponential backoff with jitter, that is, increase the wait time with each new attempt and add a random variation to avoid simultaneous retransmission of multiple requests. |
| 429 | usage_quota_exceeded | Quota enforced by the API backend because the per-client request limit was reached. Read the `Retry-After` header from the response and wait the indicated number of seconds before retrying. For greater resilience, implement exponential backoff with jitter, that is, increase the wait time with each new attempt and add a random variation to avoid simultaneous retransmission of multiple requests. |
| 500 | internal_error | Generic error. Please try submitting the request again. |

## Request example

### cURL

```bash
curl -X POST \
  'https://api.mercadopago.com/v1/orders/{order_id}/cancel' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
```

## Response example

```json
{
  "id": "ORD01J49MMW3SSBK5PSV3DFR32959",
  "processing_mode": "automatic",
  "external_reference": "ext_ref_1234",
  "total_amount": "50.00",
  "integration_data": {
  "application_id": "1234",
  "integrator_id": "dev_123",
  "platform_id": "1234567890",
  "sponsor": {
  "id": "<YOUR_SPONSOR_ID>"
  }
  },
  "user_id": "12345",
  "created_date": "2024-08-26T13:06:51.045317772Z",
  "last_updated_date": "2024-08-26T13:06:51.045317772Z",
  "country_code": "ARG",
  "type": "online",
  "status": "canceled",
  "status_detail": "canceled_transaction",
  "capture_mode": "automatic",
  "transactions": {
  "payments": [
  {
  "id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
  "amount": "24.50",
  "reference_id": "01JEVQM899NWSQC4FYWWW7KTF9",
  "status": "canceled",
  "status_detail": "canceled_transaction",
  "expiration_time": "P3Y6M4DT12H30M5S",
  "payment_method": {
  "id": null,
  "type": null,
  "token": null,
  "installments": null,
  "installment_amount": null,
  "statement_descriptor": null
  }
  }
  ]
  },
  "description": "Smartphone",
  "items": [
  {
  "title": "Smartphone",
  "unit_price": "24.50",
  "quantity": 1,
  "description": "Smartphone",
  "external_code": "1234",
  "picture_url": "https://http2.mlstatic.com/resources/frontend/statics/growth-sellers-landings/device-mlb-point-i_medium2x.png",
  "category_id": "MLB1055",
  "type": "MLB1055",
  "warranty": "true",
  "event_date": "2014-06-28T16:53:03.176-04:00"
  }
  ]
}
```