# Create order

This endpoint allows to create an order for QR Code for payment and cashout transactions. It is possible to create a payment transaction, a withdrawal transaction, or both at the same time. In case of success, the request will return a response with status 201.

**POST** `/v1/orders`

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

- `type` (string, optional)
  Order type, associated with the Mercado Pago solution for which it is created. For Mercado Pago's QR Code payments, the only possible value is "qr".
Possible enum values:

  - `qr`
  Value associated with the creation of orders for Mercado Pago QR Code payments.

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

- `description` (string, optional)
  Description of the purchased product or service, the reason for the order. The maximum limit is 150 characters and it must not contain PII data.

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

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

- `integration_data` (object, optional)
  Contains information about 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.

- `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. With its inclusion, the order information is associated with the pos and store previously created within the Mercado Pago system.

  - `config.qr.mode` (string, optional)
  QR code mode associated with the order. The possible values are listed below, and if you don't submit one, the default value will be "static".
Possible enum values:

  - `static`
  Static model, in which the static QR code, associated to the POS defined by the "external_pos_id" field, receives the order information.

  - `dynamic`
  Dynamic mode, in which a unique QR code for each transaction contains the specific data of the created order.

  - `hybrid`
  Allows payment to be made using either of the two modes, static or dynamic, since the order will be linked to the static QR code associated with the POS.

- `transactions` (object, optional)
  Contains information about the transaction associated with the order. When the type is qr, cashout transactions (cash_outs) can be included.

  - `transactions.cash_outs` (array, optional)
  Contains information about the cashout order. Only one cashout transaction can be sent per order.

  - `transactions.cash_outs.amount` (string, optional)
  Cashout amount. The field can contain two decimal places or none.

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

## Response parameters

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

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

- `external_reference` (string, optional)
  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 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:

  - `created`
  The order has been succesfully created.

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

  - `created`
  The order has been succesfully created.

- `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 created in the request, 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 cashout status.
Possible enum values:

  - `created`
  The cashout has been successfully created.

  - `transactions.cash_outs[].status_detail` (string, optional)
  Current details about the cashout.
Possible enum values:

  - `ready_to_process`
  The cashout has been succesfully created and is ready to process.

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

- `type_response` (object, optional)
  Object returned if the "config.qr.mode" field has been set to "dynamic" or "hybrid".

  - `type_response.qr_data` (string, optional)
  QR frame, which must be transformed into a QR code so that payment can be made.

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | bad_request | An attempt was made to create the order with unsupported or invalid fields. Please retry sending the request, validating all fields and. |
| 400 | empty_required_header | The "X-Idempotency-Key" header is required and was not sent. Make the request again including it. |
| 400 | marketplace_not_valid | The Access Token sent as a header in the request is not one obtained through the OAuth protocol and, therefore, it is not possible to identify a valid marketplace. Please verify that you have completed the process correctly. |
| 400 | property_value | An incorrect value for some property was sent. Check the message returned in the error details to find out what the problem was and try again. |
| 400 | property_type | An incorrect property type was sent. Check the message returned in the error details to find out what the problem was and try again. |
| 400 | sponsor_id_not_valid | An invalid value was sent as the Mercado Pago account identifier (USER_ID). Check the returned message in the error details to find out what the problem was and try again. |
| 400 | seller_configuration | The seller is not authorized to make requisitions with cashout ("cash_out") transactions. Please contact your Mercado Pago advisor to register the user and try again. |
| 400 | unsupported_site | An attempt was made to create the order from an unsupported country. Make sure you have the necessary authorization. |
| 400 | unsupported_properties | An unsupported property was sent. Check the message returned in the error details to find out what the problem was and try again. |
| 401 | unauthorized | The value sent as Access Token is incorrect. Please check and try again with the correct value. |
| 404 | marketplace_fee_not_allowed | The "marketplace_fee" field cannot be submitted because the marketplace could not be found. Please verify if the correct Access Token was sent and try again. |
| 404 | pos_not_found | The value for the "external_pos_id" field does not belong to any POS. Please confirm that you entered the correct value and try again. |
| 409 | idempotency_key_already_used | The value sent as the idempotency header has already been used with a different request within the last 24 hours. Please try the request again sending a new value. |
| 422 | — | Error. |
| 500 | 500 | Generic error. Please check the returned message and try submitting the request again. |

## Request example

### cURL

```bash
curl -X POST \
  'https://api.mercadopago.com/v1/orders' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{
  "type": "qr",
  "total_amount": "50.00",
  "description": "Smartphone",
  "external_reference": "ext_ref_1234",
  "expiration_time": "PT16M",
  "integration_data": {
  "platform_id": "dev_1234567890",
  "integrator_id": "dev_1234",
  "sponsor": {
  "id": "446566691"
  }
  },
  "config": {
  "qr": {
  "external_pos_id": "EXTERNALPOS019285",
  "mode": "static"
  }
  },
  "transactions": {
  "cash_outs": {
  "amount": "50.00",
  "additional_info": {
  "external_cashier_id": 123445
  }
  }
  }
  }'
```

## 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": "dev_1234567890",
  "platform_id": "dev_1234567890",
  "integrator_id": "dev_1234",
  "sponsor": {
  "id": "446566691"
  }
  },
  "status": "created",
  "status_detail": "created",
  "currency": "MXN",
  "created_date": "2024-09-10T14:26:42.109Z",
  "last_updated_date": "2024-09-10T14:27:42.109Z",
  "config": {
  "qr": {
  "external_pos_id": "EXTERNALPOS019285",
  "mode": "hybrid"
  }
  },
  "transactions": {
  "cash_outs": [
  {
  "id": "CAS01J67CQQH5904WDBVZEM4JMEP3",
  "amount": "50.00",
  "status": "created",
  "status_detail": "ready_to_process",
  "additional_info": {
  "external_cashier_id": null
  }
  }
  ]
  },
  "type_response": {
  "qr_data": "00020101021243650016com.mercadolibre020130636261ba79b-e543-41c7-b71a-cec05c18e72b50120008326594305204970053030325802AR5904Test6004CABA63041094"
  }
}
```