# Cancel order by ID

Cancel an order and its transactions using the reference ID obtained in the response to its creation. Only an order in "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 64 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
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 'Process order by ID' ("/v1/orders/{order_id}/process") endpoint.

  - `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 150 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.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 las 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:

  - `cancelled`
  The order has been canceled successfully.

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

  - `cancelled_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 'Capture order' ("/v1/orders/{order_id}/capture") endpoint.

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

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

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

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

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

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

  - `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 requisition 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 64 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. |
| 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_cancelled | 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. |
| 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",
  "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": "AR",
  "type": "online",
  "status": "cancelled",
  "status_detail": "canceled_transaction",
  "capture_mode": "automatic",
  "transactions": {
  "payments": [
  {
  "id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
  "amount": "24.50",
  "reference_id": "01JEVQM899NWSQC4FYWWW7KTF9",
  "status": "cancelled",
  "status_detail": "cancelled_transaction",
  "expiration_time": "P3Y6M4DT12H30M5S",
  "payment_method": {
  "id": null,
  "type": null,
  "token": null,
  "installments": null,
  "statement_descriptor": null
  }
  }
  ]
  },
  "description": "Smartphone",
  "items": [
  {
  "title": "Smartphone",
  "unit_price": "24.50",
  "quantity": 4,
  "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"
  }
  ]
}
```