# Create order

This endpoint allows to create an order for QR Code for payment transactions. 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. Represents the sum of the transactions. 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.

- `marketplace_fee` (string, optional)
  This field is exclusive to OAuth integrations. It represents the marketplace fee, which will be given to the marketplace owner account. The field can contain two decimal places or none.

- `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 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. This code must be generated from the information returned in the response, in the "qr_data" field, whose value will be unique for each 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 ("external_pos_id"), and a frame will be dynamically generated in parallel.

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

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

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

- `items` (array, optional)
  Information about the list of items to be paid. It is possible to send a maximum of 10 items.

  - `items.title` (string, optional)
  Item name. The character limit is 150.

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

  - `items.quantity` (integer, optional)
  Purchased items quantity.

  - `items.unit_measure` (string, optional)
  A value that represents a unit of measurement associated with the item. It can contain a maximum of 10 characters, and we suggest sending the value in lowercase.

  - `items.external_code` (string, optional)
  Code that identifies the item within the external system, for example, an EAN code. It is allowed a maximum of 30 characters.

  - `items.external_categories` (array, optional)
  List of categories associated with the item within the external system. A maximum of 10 categories ("id"). This field enables the category discount feature and therefore cannot be set together with the "discounts" field. If you want to apply discounts by category, use only this field ("external_categories") and remove the "discounts" field.

  - `items.external_categories.id` (string, optional)
  Identifier of the category associated with the item.

- `discounts` (object, optional)
  Contains information about the discounts the seller wants to offer on the payment transaction ("payment") of the order. Discounts can be configured for any payment method, but they will only apply if the payment is made through Mercado Pago wallet. If this node is sent, it is necessary to define the new payment value, which will replace the "total_amount" of the order. In case the payer does not use any of the payment methods assigned with a discount, the amount to be paid will continue to be the one defined in the "total_amount" field of the order. This field cannot be used with the "external categories" field. If you want to apply discounts by category, use only the "external categories" field ("external_categories") and remove this field ("discounts").

  - `discounts.payment_methods` (array, optional)
  Information about the payment method with which the discount is applied.

  - `discounts.payment_methods.new_total_amount` (string, optional)
  Defines the new total value of the order when the discount is applied. The field can contain two decimal places or none.

  - `discounts.payment_methods.type` (string, optional)
  Identifier of the payment method with which the discount will be applied if used by the payer to make the payment through Mercado Pago wallet. Discounts can be defined for the 4 payment methods listed below, and a maximum of 4 available payment methods can be entered.
Possible enum values:

  - `debit_card`
  Debit card that is registered in Mercado Pago wallet.

  - `credit_card`
  Credit card that is registered in Mercado Pago wallet.

  - `account_money`
  Available money in the Mercado Pago wallet.

  - `prepaid_card`
  Prepaid card that is registered in Mercado Pago wallet.

## 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 that is being sold, 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 amount of the order, assigned when creating it. Represents the addition of the transactions associated with the order.

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

- `marketplace_fee` (string, optional)
  This field is exclusive to OAuth integrations. It represents the marketplace fee, which will be given to the seller's account.

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

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

  - `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. The possible values ​​are listed below, and if none was submitted, 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. This code must be generated from the information returned in the response, in the "qr_data" field, whose value will be unique for each 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 ("external_pos_id"), and a frame will be dynamically generated in parallel.

- `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)
  Payment amount, assigned when creating the order.

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

  - `created`
  The payment has been succesfully created.

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

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

- `items` (array, optional)
  Information about the list of items to be paid.

  - `items[].title` (string, optional)
  Item name.

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

  - `items[].quantity` (integer, optional)
  Sold items quantity.

  - `items[].unit_measure` (string, optional)
  A value that represents a unit of measurement associated with the item, assigned when creating the order.

  - `items[].external_code` (string, optional)
  Code that identifies the item within the external system, assigned when creating the order. For example, an EAN code.

  - `items[].external_categories` (array, optional)
  List of categories associated with the item within the external system. A maximum of 10 categories ("id"). This field enables the category discount feature and therefore cannot be set together with the "discounts" field. If you want to apply discounts by category, use only this field ("external_categories") and remove the "discounts" field.

  - `items[].external_categories[].id` (string, optional)
  Identifier of the category associated with the item.

- `discounts` (object, optional)
  Contains information about the discounts the seller set for the payment transaction ("payment") of the order, associated with a payment method.

  - `discounts.payment_methods` (array, optional)
  Information about the payment method selected to apply the discount, assigned when creating the order.

  - `discounts.payment_methods[].new_total_amount` (string, optional)
  New total value of the order when the discount is applied.

  - `discounts.payment_methods[].type` (string, optional)
  Identifier of the payment method with which the discount will be applied if used by the payer to make the payment.
Possible enum values:

  - `debit_card`
  Debit card that is registered in Mercado Pago wallet.

  - `credit_card`
  Credit card that is registered in Mercado Pago wallet.

  - `account_money`
  Available money in the Mercado Pago wallet.

  - `prepaid_card`
  Prepaid card that is registered in Mercado Pago wallet.

- `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 | empty_required_header | The "X-Idempotency-Key" header is required and was not sent. Make the request again including it. |
| 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. |
| 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 | 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 | 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 | 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. |
| 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. |
| 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",
  "marketplace_fee": "11.20",
  "integration_data": {
  "platform_id": "dev_1234567890",
  "integrator_id": "dev_1234",
  "sponsor": {
  "id": "446566691"
  }
  },
  "config": {
  "qr": {
  "external_pos_id": "EXTERNALPOS019285",
  "mode": "static"
  }
  },
  "transactions": {
  "payments": {
  "amount": "24.50"
  }
  },
  "items": {
  "title": "Smartphone",
  "unit_price": "24.50",
  "quantity": 1,
  "unit_measure": "kg",
  "external_code": "777489134",
  "external_categories": {
  "id": "device"
  }
  },
  "discounts": {
  "payment_methods": {
  "new_total_amount": "47.28",
  "type": "account_money"
  }
  }
  }'
```

## 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": "AR",
  "marketplace_fee": "11.20",
  "integration_data": {
  "application_id": "1234567890",
  "platform_id": "dev_1234567890",
  "integrator_id": "dev_1234",
  "sponsor": {
  "id": "446566691"
  }
  },
  "status": "created",
  "status_detail": "created",
  "currency": "ARS",
  "created_date": "2024-09-10T14:26:42.109Z",
  "last_updated_date": "2024-09-10T14:27:42.109Z",
  "config": {
  "qr": {
  "external_pos_id": "EXTERNALPOS019285",
  "mode": "static"
  }
  },
  "transactions": {
  "payments": [
  {
  "id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
  "amount": "24.50",
  "status": "created",
  "status_detail": "ready_to_process"
  }
  ]
  },
  "items": [
  {
  "title": "Smartphone",
  "unit_price": "24.50",
  "quantity": 1,
  "unit_measure": "kg",
  "external_code": "777489134",
  "external_categories": [
  {
  "id": null
  }
  ]
  }
  ],
  "discounts": {
  "payment_methods": [
  {
  "new_total_amount": "47.28",
  "type": "account_money"
  }
  ]
  },
  "type_response": {
  "qr_data": "00020101021243650016com.mercadolibre020130636261ba79b-e543-41c7-b71a-cec05c18e72b50120008326594305204970053030325802AR5904Test6004CABA63041094"
  }
}
```