# Update merchant order

Renew the details of a payment. Indicate the ID of the order and send the parameters with the information you want to update.

**PUT** `/merchant_orders/{id}`

## Request parameters

### Path

- `id` (number, required)
  Unique identifier of the order generated by Mercado Pago

- `external_reference` (string, optional)
  Unique identifier sent by the seller to relate the order_id generated by Mercado Pago, with the id of their payment system

- `preference_id` (string, optional)
  Identifier of the payment preference associated to the order

- `marketplace` (string, optional)
  Indicates if it is a Mercado Libre (MELI) or Mercado Pago (NONE) Marketplace payment

- `notification_url` (string, optional)
  URL where you'd like to receive a payment notification.

- `sponsor_id` (number, optional)
  Identifier of the Partners Mercado Pago account. It is used to identify if the integration was performed by a partner.

- `payer` (object, optional)
  Buyer's information.

  - `payer.id` (number, optional)
  Buyer id.

  - `payer.email` (string, optional)
  Deprecated field, will return an empty string.

  - `payer.nickname` (string, optional)
  Buyer nickname.

- `site_id` (string, optional)
  Site ID.
Possible enum values:

  - `MLA`
  Mercado Libre Argentina

  - `MLB`
  Mercado Libre Brasil

  - `MLM`
  Mercado Libre México

  - `MLC`
  Mercado Libre Chile

  - `MLU`
  Mercado Libre Uruguay

  - `MCO`
  Mercado Libre Colombia

  - `MPE`
  Mercado Libre Perú

- `items` (array, optional)
  items information.

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

  - `items[].category_id` (string, optional)
  This is a free string where the item category can be added.

  - `items[].currency_id` (string, optional)
  ID of the currency used in the payment.
Possible enum values:

  - `ARS`
  Argentine peso.

  - `BRL`
  Brazil real.

  - `CLP`
  Chilean peso.

  - `MXN`
  Mexican peso.

  - `COP`
  Colombian peso.

  - `PEN`
  Peruvian sol.

  - `UYU`
  Uruguayan peso.

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

  - `items[].picture_url` (string, optional)
  Item picture URL.

  - `items[].quantity` (number, optional)
  Item quantity.

  - `items[].unit_price` (number, optional)
  Item unit price.

  - `items[].title` (string, optional)
  Item title. It will be displayed in the payment process.

- `additional_info` (string, optional)
  Additional information.

- `application_id` (string, optional)
  application identifier.

## Response parameters

- `id` (number, optional)
  Unique identifier of the order generated by Mercado Pago

- `status` (string, optional)
  Show the current merchant order state.
Possible enum values:

  - `opened`
  Order without payments.

  - `closed`
  Order with payments covering total amount.

  - `expired`
  Canceled order that does not have approved or pending payments (all rejected or returned).

- `external_reference` (string, optional)
  Unique identifier sent by the seller to relate the order_id generated by Mercado Pago, with the id of their payment system

- `preference_id` (string, optional)
  Identifier of the payment preference associated to the order

- `payments` (object, optional)
  Payment Attributes associated with the Order

- `shipments` (object, optional)
  Shipment Attributes

- `payouts` (object, optional)
  Contains information on cash withdrawal, if applicable.

- `collector` (object, optional)
  Attributes of the Mercado Pago account collecting the payment

  - `collector.id` (number, optional)
  Identifier of the collecting Mercado Pago account

  - `collector.email` (string, optional)
  Email associated with the collector´s Mercado Pago account

  - `collector.nickname` (string, optional)
  Collector nickname.

- `marketplace` (string, optional)
  Indicates if it is a Mercado Libre (MELI) or Mercado Pago (NONE) Marketplace payment

- `notification_url` (string, optional)
  URL where you'd like to receive a payment or merchant_order notification.

- `date_created` (string, optional)
  Order creation date. The format is YYYY-MM-DDThh:mm:ss.dcm-GMT, for example 2021-12-29T20:19:17.000-04:00.

- `last_updated` (string, optional)
  Date of last update of the order. The format is YYYY-MM-DDThh:mm:ss.dcm-GMT, for example 2021-12-29T20:19:17.000-04:00.

- `sponsor_id` (string, optional)
  Identifier of the Partners Mercado Pago account. It is used to identify if the integration was performed by a partner.

- `shipping_cost` (number, optional)
  Shipping cost, if applicable

- `total_amount` (number, optional)
  Total amount of the transaction in local currency.

- `site_id` (string, optional)
  Site ID.
Possible enum values:

  - `MLA`
  Mercado Libre Argentina

  - `MLB`
  Mercado Libre Brasil

  - `MLM`
  Mercado Libre México

  - `MLC`
  Mercado Libre Chile

  - `MLU`
  Mercado Libre Uruguay

  - `MCO`
  Mercado Libre Colombia

  - `MPE`
  Mercado Libre Perú

- `paid_amount` (number, optional)
  Paid amount

- `refunded_amount` (number, optional)
  Refunded amount

- `payer` (object, optional)
  Buyer's information.

  - `payer.id` (number, optional)
  Payer ID.

  - `payer.email` (string, optional)
  Payer’s email address.

- `items` (array, optional)
  Order item attributes

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

  - `items[].category_id` (string, optional)
  This is a free string where the item category can be added.

  - `items[].currency_id` (string, optional)
  ID of the currency used in the payment.
Possible enum values:

  - `ARS`
  Argentine peso.

  - `BRL`
  Brazil real.

  - `CLP`
  Chilean peso.

  - `MXN`
  Mexican peso.

  - `COP`
  Colombian peso.

  - `PEN`
  Peruvian sol.

  - `UYU`
  Uruguayan peso.

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

  - `items[].picture_url` (string, optional)
  Item image URL.

  - `items[].title` (string, optional)
  Item title. It will be displayed in the payment process.

  - `items[].quantity` (number, optional)
  Item quantity.

  - `items[].unit_price` (number, optional)
  Item unit price.

- `canceled` (boolean, optional)
  Boolean value that indicates if the order was canceled

- `additional_info` (string, optional)
  Additional information.

- `application_id` (string, optional)
  application identifier.

- `order_status` (string, optional)
  Current merchant order status given the payments status.
Possible enum values:

  - `payment_required`
  Order without payments or with all payments "rejected" or "canceled".

  - `reverted`
  Order with all payments "refunded" or "chargeback".

  - `paid`
  Order with the sum of all payments "approved", "chargeback" or "in_mediation", covers the order total amount.

  - `partially_reverted`
  Order with at least one payment "refunded" or "chargeback".

  - `partially_paid`
  Order with at least one payment "approved" and not covering order total amount.

  - `payment_in_process`
  Order with payments "in_process", "pending" or "authorized".

  - `undefined`
  Order created before the existence of the order_status status.

  - `expired`
  Canceled order that does not have approved or pending payments (all rejected or returned).

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | invalid_user_id | invalid users involved. |
| 400 | invalid_order_state | the action requested is not valid for the current merchant order state. |
| 400 | invalid_string | string too long. |
| 400 | invalid_application_id | internal server error. |
| 400 | invalid_items | only the item quantity of an item can be modified. |
| 400 | user_not_allowed | user not allowed to operate. |
| 400 | invalid_payment_id | invalid payment identifier. |
| 400 | invalid_operation_type | invalid operation type. |
| 400 | invalid_payer | invalid payer identifier. |
| 400 | invalid_shipment_id | invalid shipment identifier. |
| 400 | invalid_sponsor_id | invalid sponsor_id. |
| 400 | invalid_marketplace | invalid marketplace. |
| 400 | unmarshall_error | could not unmarshal request body into merchant order struct. |
| 400 | invalid_format | invalid merchant order id. |
| 400 | invalid_url | invalid URL. Isn't HTTP or HTTPS. |
| 400 | communication_error | Error when calling... |
| 401 | invalid_token | access denied. |
| 401 | invalid_caller_id | invalid caller_id |

## Request example

### cURL

```bash
curl -X PUT \
  'https://api.mercadopago.com/merchant_orders/{id}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{
  "external_reference": "default",
  "preference_id": "Preference identification",
  "marketplace": "string",
  "notification_url": "string",
  "sponsor_id": 0,
  "payer": {
  "id": 123,
  "email": "string",
  "nickname": "JOHN"
  },
  "site_id": "MLA",
  "items": [
  {
  "id": "item id",
  "category_id": "item category",
  "currency_id": "BRL",
  "description": "item description",
  "picture_url": "item picture",
  "quantity": 1,
  "unit_price": 5,
  "title": "item title"
  }
  ],
  "additional_info": "string",
  "application_id": "10000000000000000"
  }'
```

## Response example

```json
{
  "id": 9999999999,
  "status": "closed",
  "external_reference": "default",
  "preference_id": "Preference identification",
  "payments": {},
  "shipments": {},
  "payouts": {},
  "collector": {
  "id": 999999999,
  "email": "test@testuser.com",
  "nickname": "TESTRPEHE21Q"
  },
  "marketplace": "NONE",
  "notification_url": "string",
  "date_created": "2018-09-14T17:11:31.000Z",
  "last_updated": "2018-09-14T17:11:43.000Z",
  "sponsor_id": "string",
  "shipping_cost": 0,
  "total_amount": 5,
  "site_id": "mla",
  "paid_amount": 5,
  "refunded_amount": 0,
  "payer": {
  "id": 999999999,
  "email": "test@testuser.com"
  },
  "items": [
  {
  "id": "item id",
  "category_id": "item category",
  "currency_id": "BRL",
  "description": "item description",
  "picture_url": "item picture url",
  "title": "item title",
  "quantity": 1,
  "unit_price": 5
  }
  ],
  "canceled": false,
  "additional_info": "additional information",
  "application_id": "10000000000000000",
  "order_status": "paid"
}
```