How to migrate from the Instore Orders V2 API to the Orders API

The Orders API unifies payment processing with QR Code on Mercado Pago, offering standardized endpoints, a consolidated status model, and new native features that did not exist in the Instore Orders V2 API. In addition, all new Mercado Pago features will be developed on the Orders API.

Migrating from the Instore Orders V2 API to the Orders API involves updating endpoints and request fields, consolidating the notifications model, and taking advantage of new native features, such as dedicated cancel and refund endpoints. The main change in creation is that the Orders API returns 201 Created with the complete order object, instead of 204 No Content without a body. The migration does not involve changes to the business flow: the customer continues scanning the QR Code with the Mercado Pago app and confirming the payment.

See below how to carry out this migration in full.

Before starting the migration steps, refer to the table below for an overview of all endpoint changes. In the Instore Orders V2 API, each operation used a URL with the user, store, and POS identifier in the path. The Orders API consolidates these operations into standardized endpoints identified by the order_id.

One of the most significant changes between the Instore Orders V2 API and the Orders API is the status model. In the Instore Orders V2 API, the state of a transaction was determined by monitoring notifications from two independent topics , payments and merchant_orders, with distinct fields and values for each. The Orders API unifies this behavior in a single status field on the order. See the complete mapping below.

In addition, the Orders API also introduces the status_detail field, which provides greater detail on the transaction state. The possible values are created, canceled, accredited, refunded, and expired.

Regarding notifications, in the Legacy API they could be configured via the notification_url field in the request body (IPN model) or via webhooks with the payments and merchant_orders topics. In the Orders API, the notification_url field does not exist and the payments and merchant_orders topics are not compatible. Configure notifications in Your integrations, subscribing to the "Order (Mercado Pago)" (orders) topic, before going to production. For more information, see the notifications documentation.

The Orders API introduces a mandatory header change that affects all endpoints. The Access Token must be sent via the Authorization header. Sending it as a query parameter is not allowed in the Orders API. Apply the change below before testing any other resource.

The creation endpoint changes from PUT /instore/qr/seller/collectors/{user_id}/stores/{external_store_id}/pos/{external_pos_id}/ordersAPI to POST /v1/ordersAPI. In addition to the method change from PUT to POST and the URL change, the response changes from HTTP 204 No Content without a body to 201 Created with the complete order object. The {user_id} and the store and POS path parameters are removed. Identity comes from the Access Token and the POS is identified by the config.qr.external_pos_id field in the body. Follow the steps below to adapt the request, the response, and error handling.

The query endpoint changes from GET /instore/qr/seller/collectors/{user_id}/pos/{external_pos_id}/ordersAPI to GET /v1/orders/{order_id}API. In the Instore Orders V2 API, queries were made by POS (external_pos_id), returning the active order at that POS without exposing the transaction state. The Orders API replaces the POS-based query endpoint with one that operates directly by order_id and returns the complete transaction state: status, payments, refunds, and payment method data. In the Instore Orders V2 API, this information only arrived via notification.

curl
Copiar
curl -X GET \
  'https://api.mercadopago.com/v1/orders/{{ORDER_ID}}' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

The cancellation endpoint changes from DELETE /instore/qr/seller/collectors/{user_id}/pos/{external_pos_id}/ordersAPI to POST /v1/orders/{order_id}/cancelAPI. The HTTP method changes from DELETE to POST, the {user_id} and {external_id} are removed from the path, and cancellation now operates on the order_id. The response changed from empty (HTTP 204) to the complete order object with status: "canceled" (HTTP 200).

In the Instore Orders V2 API, cancellation deleted the active order associated with the POS, an operation on the POS rather than the individual transaction. In the Orders API, cancellation operates directly on the order via order_id, without depending on the POS in the path.

The Orders API introduces the dedicated endpoint POST /v1/orders/{order_id}/refundAPI for refunds, which did not exist in the Instore Orders V2 API. Previously, it was necessary to receive the payment webhook, obtain the payment_id, and execute the refund through the Payments API separately. Now, the refund is performed directly on the order.

curl
Copiar
curl -X POST \
  'https://api.mercadopago.com/v1/orders/{{ORDER_ID}}/refund' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'X-Idempotency-Key: {{IDEMPOTENCY_KEY}}'

After applying the changes, verify that the integration operates correctly across all flows before going to production.

See the documentation to learn how to test the integration.