# Cancel order by ID

Cancel an order created for Mercado Pago QR Code and all its transactions using the reference ID obtained in the response to its creation. Only an order in "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, you must use an exclusive value in the header of each unique value for each call. If you use a value already assigned to another request, you will receive information corresponding to that created resource in response, not this new request. We suggest using a UUID V4 or random strings.

### 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 canceled in the request.

- `user_id` (string, optional)
  ID of the Mercado Pago account that created the order.

- `type` (string, optional)
  Order type.
Possible enum values:

  - `qr`
  Order created for Mercado Pago QR payments.

- `external_reference` (string, optional)
  It is the external reference of the order, assigned when creating it.

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

- `expiration_time` (string, optional)
  Specifies the order's validity period in ISO 8601 duration format (e.g., P3Y6M4DT12H30M5S). Minimum of 30 seconds and maximum of 3600 hours. Behavior varies by QR model. Dynamic QR defaults to 15 minutes and honors the value sent. Static QR defaults to 10 minutes and is capped at 10 minutes regardless of the value sent. Hybrid QR follows the same rules per type: the Dynamic QR honors the value sent, while the linked Static QR is always capped at 10 minutes.

- `processing_mode` (string, optional)
  Indicates how the order will be processed. For QR Code orders, the only allowed value is "automatic", that sets the order to be ready to process.

- `total_amount` (string, optional)
  Total order amount.The field can contain two decimal places or none.

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

- `integration_data` (object, optional)
  Contains information about the Mercado Pago application that created the order.

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

  - `integration_data.platform_id` (string, optional)
  Identifier of the platform, assigned by Mercado Pago.

  - `integration_data.integrator_id` (string, optional)
  Identifier of the user who develops the integration that creates the order, assigned by Mercado Pago. It must contain the prefix "dev_"

  - `integration_data.sponsor` (object, optional)

  - `integration_data.sponsor.id` (string, optional)
  Mercado Pago's USER_ID of the integrator system.

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

  - `canceled`
  The order has been canceled through the API.

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

  - `canceled`
  The order has been canceled.

- `currency` (string, optional)
  Identifier of the currency used in the order. We currently have the following options.
Possible enum values:

  - `BRL`
  Brazilian real.

  - `ARS`
  Argentine peso.

  - `CLP`
  Chilean peso.

  - `MXN`
  Mexican peso.

  - `UYU`
  Urugayan peso.

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

- `config` (object, optional)
  Order type configuration.

  - `config.qr` (object, optional)
  QR Code order configuration.

  - `config.qr.external_pos_id` (string, optional)
  External identifier of the POS, defined by the integrator during its creation.

  - `config.qr.mode` (string, optional)
  QR code mode associated with the order.

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

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

  - `transactions.cash_outs[].id` (string, optional)
  Identifier of the cashout transaction, automatically generated by Mercado Pago.

  - `transactions.cash_outs[].amount` (string, optional)
  Cashout amount, assigned when creating the order.

  - `transactions.cash_outs[].status` (string, optional)
  Current status of the cashout.
Possible enum values:

  - `canceled`
  The cashout has been successfully canceled.

  - `transactions.cash_outs[].status_detail` (string, optional)
  Details about cashout status. It is returned exclusively when the cancellation of the order is made through this endpoint, with the value "canceled_by_api".

  - `transactions.cash_outs[].additional_info` (object, optional)
  Specifies additional cashout information.

  - `transactions.cash_outs[].additional_info.external_cashier_id` (number, optional)
  Identifier of the cashier performing the transaction. It can take any value.

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | empty_required_header | The "X-Idempotency-Key" header is required and was not sent. Make the requisition again including it. |
| 400 | invalid_path_param | The Order ID provided in the request path has has an invalid format. It must begin with the prefix "ORD" and be followed by 26 characters. Please confirm it and provide a valid ID to try again. |
| 401 | unauthorized | The value sent as Access Token is incorrect. Please check and try again with the correct value. |
| 404 | order_not_found | The value sent as Order ID does not correspond to a created order, therefore it could not be found. Please check and try again with the correct value. |
| 409 | idempotency_key_already_used | The value sent as the idempotency header has already been used. Please try the request again sending a new value. |
| 409 | order_already_canceled | There is a conflict trying to cancel the order due to its current status. Please note that orders can only be canceled via API when "status=created". |
| 500 | 500 | Internal server 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": "ORD00001111222233334444555566",
  "user_id": "5238400195",
  "type": "qr",
  "external_reference": "ext_ref_1234",
  "description": "Smartphone",
  "expiration_time": "PT16M",
  "processing_mode": "automatic",
  "total_amount": "50.00",
  "country_code": "MX",
  "integration_data": {
  "application_id": "1234567890",
  "platform_id": "dev_1234567890",
  "integrator_id": "dev_1234",
  "sponsor": {
  "id": "446566691"
  }
  },
  "status": "canceled",
  "status_detail": "canceled",
  "currency": "MXN",
  "created_date": "2024-09-10T14:26:42.109320977Z",
  "last_updated_date": "2024-09-10T14:26:42.109320977Z",
  "config": {
  "qr": {
  "external_pos_id": "EXTERNALPOS019285",
  "mode": "hybrid"
  }
  },
  "transactions": {
  "cash_outs": [
  {
  "id": "CAS01J67CQQH5904WDBVZEM4JMEP3",
  "amount": "50.00",
  "status": "canceled",
  "status_detail": "canceled_by_api",
  "additional_info": {
  "external_cashier_id": null
  }
  }
  ]
  }
}
```