# 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. Represents the sum of the transactions, so if it includes payment transactions ("payments") and cash_outs ("cash_outs"), it must be the sum of both values. 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 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.

  - `config.payment_method` (object, optional)
  Payment method configuration node. Should only be used to configure interest-free installments. Cannot be used if the "transactions.cashouts" or "discounts" nodes are sent in the request.

  - `config.payment_method.default_type` (string, optional)
  Payment method type to which the installment configuration applies. Accepts only the value "credit_card", which indicates that the configuration will be applied when the payment is processed by credit card.
Possible enum values:

  - `credit_card`
  Indicates that the payment is processed by credit card.

  - `config.payment_method.installments_cost` (string, optional)
  Defines who bears the cost of installment interest. "seller": the seller absorbs the interest cost without passing it on to the buyer. "buyer": the buyer bears the interest cost. This node is not compatible with the "discounts" node.
Possible enum values:

  - `seller`
  The seller absorbs the interest cost without passing it on to the buyer.

  - `buyer`
  The buyer bears the interest cost.

  - `config.payment_method.installments` (object, optional)
  Node containing the configuration of installment options available for the transaction. Can only be used when "installments_cost" is "seller".

  - `config.payment_method.installments.interest_free` (object, optional)
  Configuration of interest-free installments available to the buyer during payment.

  - `config.payment_method.installments.interest_free.type` (string, optional)
  Defines the configuration format of interest-free installments. "range": installments are defined as a continuous range; all installments between the minimum and maximum values will be offered interest-free. The range must always start at 1. For example, [1,3] configures installments 1, 2, and 3 as interest-free. "list": only one specific installment is configured interest-free. Accepts only one value. For example, [5] configures only installment 5 as interest-free.
Possible enum values:

  - `range`
  Installments are defined as a continuous range; all installments between the minimum and maximum values will be offered interest-free. The range must always start at 1.

  - `list`
  Only one specific installment is configured interest-free. Accepts only one value.

  - `config.payment_method.installments.interest_free.values` (array, optional)
  Values that define the interest-free installments. If type="range", provide two values representing the minimum and maximum, with a minimum of 1. Example: [1,3]. If type="list", provide a single installment value. Example: [3].

  - `config.payment_method.installments.interest_free.values.value` (integer, optional)

  - `config.payment_method.installments.available` (object, optional)
  Configuration of additional installments to be displayed to the buyer, beyond those configured in interest_free. Only available when interest_free.type is "range".

  - `config.payment_method.installments.available.type` (string, optional)
  Defines which additional installments will be displayed. "all": shows all installments supported by the payment method.
Possible enum values:

  - `all`
  Shows all available installments according to the payment method.

- `transactions` (object, optional)
  Contains information about the transaction associated with the order. When the type is qr, both payment transactions (payments) and cashout transactions (cash_outs) can be included. At a minimum, at least one payments or one cash_outs must 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.

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

- `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` (number, 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. If the created order contains both cashouts and payments, the value of this field must be the sum of the cashout amount plus the payment amount with the discount applied, and it cannot be less or equal to the cashout amount. 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 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. Represents the sum of the transactions, so if it includes payment transactions ("payments") and cash_outs ("cash_outs"), it must be the sum of both values. 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.

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

  - `config.payment_method` (object, optional)
  Payment method configuration sent in the request, returned in the response when present.

  - `config.payment_method.default_type` (string, optional)
  Payment method type to which the installment configuration applies.

  - `config.payment_method.installments_cost` (string, optional)
  Defines who bears the cost of installment interest.

  - `config.payment_method.installments` (object, optional)
  Configuration of available installment options.

  - `config.payment_method.installments.interest_free` (object, optional)
  Configuration of interest-free installments.

  - `config.payment_method.installments.interest_free.type` (string, optional)
  Defines the configuration format of interest-free installments. "range": installments are defined as a continuous range; all installments between the minimum and maximum values will be offered interest-free. The range must always start at 1. For example, [1,3] configures installments 1, 2, and 3 as interest-free. "list": only one specific installment is configured interest-free. Accepts only one value. For example, [5] configures only installment 5 as interest-free.

  - `config.payment_method.installments.interest_free.values` (array, optional)
  Available interest-free installment values.

  - `config.payment_method.installments.available` (object, optional)
  Configuration of additional installments to be displayed to the buyer, beyond those configured in interest_free. Only available when interest_free.type is "range".

  - `config.payment_method.installments.available.type` (string, optional)
  Defines which additional installments will be displayed. "all": shows all installments supported by the payment method, even if not configured in interest_free. Installments configured in interest_free are shown interest-free and the remaining ones with interest. For example, if interest_free.values is [1,3] and available.type is all, installments 1, 2, and 3 are shown interest-free and the remaining ones with interest. Only available if interest_free.type is "range". If not sent, only the installments in interest_free will be shown to the buyer.

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

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

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

  - `items[].quantity` (number, optional)
  Purchased 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. If the created order contains both cashouts and payments, the value of this field will be the sum of the cashout amount plus the payment amount with the discount 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 | 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. |
| 400 | discounts_not_allowed_with_installments | The `discounts` node is not compatible with `installments_cost`. Remove `discounts` from the request or do not include `installments_cost`. |
| 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 | cashout_not_allowed_with_installments_cost | The `transactions.cashouts` node is not compatible with `installments_cost`. Orders that include installment financing cannot contain cashout transactions. |
| 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"
  },
  "payment_method": {
  "default_type": "credit_card",
  "installments_cost": "seller",
  "installments": {
  "interest_free": {
  "type": null,
  "values": null
  },
  "available": {
  "type": null
  }
  }
  }
  },
  "transactions": {
  "payments": {
  "amount": "24.50"
  },
  "cash_outs": {
  "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": "dev_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": "hybrid"
  },
  "payment_method": {
  "default_type": "credit_card",
  "installments_cost": "seller",
  "installments": {
  "interest_free": {
  "type": null,
  "values": null
  },
  "available": {
  "type": null
  }
  }
  }
  },
  "transactions": {
  "payments": [
  {
  "id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
  "amount": "24.50",
  "status": "created",
  "status_detail": "ready_to_process"
  }
  ],
  "cash_outs": [
  {
  "id": "CAS01J67CQQH5904WDBVZEM4JMEP3",
  "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"
  }
}
```