# Cancel order by ID

Cancel an order created for Mercado Pago Point and 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:

  - `point`
  Order created for Mercado Pago Point payments.

- `external_reference` (string, optional)
  It is the external reference of the order, assigned when creating it. he maximum allowed limit is 64 characters, and the allowed characters are: uppercase and lowercase letters, numbers, and the symbols hyphen (-) and underscore (_).

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

- `expiration_time` (string, optional)
  Indicates the validity period of the payment order from its creation. During this time, the order will be available for processing by the customer; if it is not processed within the specified period, it will automatically expire and cannot be used, requiring the generation of a new payment order to continue. The minimum allowed value is 30 seconds (PT30S) and the maximum is 3 hours (PT3H). Usage examples: for a 30-second expiration: " PT30S ", for 10 minutes: " PT10M ", and for 1 hour and 15 minutes: " PT1H15M ".

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

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

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

  - `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, either through the API or the terminal.

  - `at_terminal`
  The cancellation request via API was accepted, but the proper cancellation will only be effective after receiving a cancellation notification.

- `status_detail` (string, optional)
  Details about payment status. It is returned exclusively when the order is canceled through the API.
Possible enum values:

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

  - `at_terminal`
  The cancellation request via API was accepted at terminal, but the proper cancellation will only be effective after receiving a cancellation notification.

- `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.point` (object, optional)
  Point order configuration.

  - `config.point.screen_time` (string, optional)
  Indicates the time that the terminal screens will be enabled for the order to be processed, using the ISO 8601 duration format (for example: "PT1M15S" represents a duration of 1 minute and 15 seconds; the minimum allowed time is 5 seconds and the maximum is 5 minutes). This time resets every time the screen changes or there is user interaction with the terminal. If this field is not configured, the default value will be 15 seconds. During the configured period, the order will be available to be processed, and if it is not processed within this time, it will be canceled. To continue with the payment, you must create a new order. Important: the card reading screen for payment will be displayed for a maximum of 60 seconds (1 minute), regardless of whether the value configured for this field is greater than 60 seconds.

  - `config.point.terminal_id` (string, optional)
  Identifier of the terminal that will obtain the order. You must send it according to the following format: "type of terminal + "__" + terminal serial", as in the following example: "PAX_N950__SMARTPOS123456789". The serial number can be found on the rear label of the terminal.

  - `config.point.print_on_terminal` (string, optional)
  Indicates whether the terminal should print the receipt of the transaction. Its default value will be "seller_ticket".
Possible enum values:

  - `seller_ticket`
  Value that determines the printing of the ticket for the seller.

  - `no_ticket`
  Value that determines that the ticket must not be printed.

  - `config.point.ticket_number` (string, optional)
  An alphanumeric value to identify the invoice or ticket number. It will be printed on the terminal ticket, if its printing whas selected.

  - `config.payment_method` (object, optional)
  Order's payment method configuration.

  - `config.payment_method.default_type` (string, optional)
  Indicates the payment method that the terminal will accept. By default, it will accept all payment methods and will allow the customer to select the payment method they want. If not, the possible values ​​are the following:
Possible enum values:

  - `debit_card`
  The terminal will accept debit and credit card payments.

  - `credit_card`
  The terminal will accept debit and credit card payments.

- `transactions` (object, optional)
  Contains information about the transaction 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)
  Payment amount.

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

  - `canceled`
  The order has been canceled, either through the API or the terminal.

  - `at_terminal`
  The cancellation request via API was accepted, but the cancellation will only be effective after receiving a cancellation notification.

  - `transactions.payments[].status_detail` (string, optional)
  Details about payment status. It is returned exclusively when the cancellation of the order is made through this endpoint.
Possible enum values:

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

## 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 is not correct. 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 | Order not found. Please check if you provided the correct order ID. |
| 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 | cannot_cancel_order | There is a conflict trying to cancel the order due to its current status. Please note that orders can only be cancelled via API when "status=created". If you are trying to cancel an order with "status=at_terminal", you will need to do from the terminal. |
| 409 | order_already_canceled | The order has already been canceled. |
| 500 | idempotency_validation_failed | Validation fail. Please try submitting the request again. |
| 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": "ORD0000ABCD222233334444555566",
  "user_id": "5238400195",
  "type": "point",
  "external_reference": "ext_ref_1234",
  "description": "Point Smart Mini",
  "expiration_time": "PT16M",
  "country_code": "AR",
  "processing_mode": "automatic",
  "integration_data": {
  "application_id": "1234567890",
  "platform_id": "dev_1234567890",
  "integrator_id": "dev_123456",
  "sponsor": {
  "id": "446566691"
  }
  },
  "status": "canceled",
  "status_detail": "canceled",
  "created_date": "2024-09-10T14:26:42.109320977Z",
  "last_updated_date": "2024-09-10T14:26:42.109320977Z",
  "config": {
  "point": {
  "screen_time": "PT15S",
  "terminal_id": "PAX_N950__SMARTPOS1423",
  "print_on_terminal": "no_ticket",
  "ticket_number": "S0392JED"
  },
  "payment_method": {
  "default_type": "credit_card"
  }
  },
  "transactions": {
  "payments": [
  {
  "id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
  "amount": "24.50",
  "status": "canceled",
  "status_detail": "canceled_by_api"
  }
  ]
  }
}
```