# Cancel order by ID

This endpoint allows to cancel an order that has not yet been paid using the ID obtained in the response to its creation. Only orders in "created" or "action_required" status can be canceled. Cancellation releases any reserved balance when applicable. In case of success, the request will return a response with status 200.

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

## Request parameters

### Header

- `Authorization` (string, required)
  Access token to authenticate the request. For more information, see the [Authentication](https://www.mercadopago.com/developers/en/docs/your-integrations/credentials) documentation.

- `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 orders. 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 'Create order' ("/v1/orders") request.

## 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. For payments with Checkout Pro, the only possible value is "manual".
Possible enum values:

  - `manual`
  Order's processing will be made manually. This mode is used by Checkout Pro, allowing the order to be processed later through its payment flow.

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

- `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.corporation_id` (string, optional)
  Identifier of the corporation in Mercado Pago. It is the unique identifier of the corporation 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. For Checkout Pro online flows, the value is always "automatic_async", meaning the order may go through an intermediate state before being approved or rejected.
Possible enum values:

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

  - `automatic_async`
  The order can be processed asynchronously.

- `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. Access the endpoint "/v1/payment_methods" to check all available payment methods and get a list with the details of each one and their properties. The requirement of this parameter varies according to the need to send its attributes in the request. Depending on the payment method you are integrating, check below which of these attributes are required.

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

  - `pse`
  Payment with "PSE" (Pagos Seguros en Línea), a digital payment method that allows you to use funds online directly from your savings account, checking account, or digital wallet.

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

  - `bank_transfer`
  Bank transfer.

  - `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 in the Checkout API documentation.

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

  - `transactions.payments[].payment_method.statement_descriptor` (string, optional)
  Description that the payment will appear with in the card statement. Accepts up to 50 characters.

  - `transactions.payments[].payment_method.financial_institution` (string, optional)
  Code of the financial institution where the buyer will make the electronic transfer to complete the payment. Required only for PSE payments.

- `client_token` (string, optional)
  Authentication token to render the Checkout Pro UI on the client side. It is a short-lived JWT generated for this order.

- `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. Multiple items are supported. The "total_amount" must equal the sum of "unit_price" multiplied by "quantity" across all items.

  - `items[].external_code` (string, optional)
  Item external code. The character limit is 30.

  - `items[].title` (string, optional)
  Item name. Displayed in the Checkout Pro flow. The character limit is 256.

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

  - `items[].category_id` (string, optional)
  Item category ID. Used by the fraud prevention system.

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

  - `items[].quantity` (integer, optional)
  Purchased items quantity. The minimum value is 1.

  - `items[].unit_price` (string, optional)
  Unit price of the purchased item. It can contain two decimal places or none.

  - `items[].type` (string, optional)
  Item type for vertical industry purposes.

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

  - `items[].event_date` (string, optional)
  Date of the event associated with the item (ISO 8601). Used for travel and event industry verticals.

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | empty_required_header | The "X-Idempotency-Key" header is required and was not sent. Make the request again including it. |
| 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. |
| 404 | order_not_found | Order not found. Please check if you provided the correct order ID. |
| 409 | order_already_canceled | Cannot cancel order. Only orders with status "created" or "action_required" can be canceled. Check the message returned in the error details to find out what the problem was and try again. |
| 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": "manual",
  "external_reference": "ext_ref_1234",
  "total_amount": "50.00",
  "integration_data": {
  "application_id": "1234",
  "integrator_id": "dev_123",
  "platform_id": "1234567890",
  "corporation_id": "string",
  "sponsor": {
  "id": "446566691"
  }
  },
  "user_id": "12345",
  "created_date": "2024-08-26T13:06:51.045317772Z",
  "last_updated_date": "2024-08-26T13:06:51.045317772Z",
  "country_code": "CO",
  "type": "online",
  "status": "canceled",
  "status_detail": "canceled_transaction",
  "capture_mode": "automatic_async",
  "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,
  "statement_descriptor": null,
  "financial_institution": null
  }
  }
  ]
  },
  "client_token": "eyJhbGciOiJSUzI1NiIs...",
  "description": "Smartphone",
  "items": [
  {
  "external_code": "ITEM-001",
  "title": "Product 001",
  "description": "Product description",
  "category_id": "travels",
  "picture_url": "https://example.com/img.jpg",
  "quantity": 1,
  "unit_price": "1000.00",
  "type": "travel",
  "warranty": true,
  "event_date": "2014-06-28T16:53:03.176-04:00"
  }
  ]
}
```