# Search order

This endpoint allows you to search for orders in a massive way, using various filters and pagination information. In case of success, the request will return a response with status 200.

**GET** `/v1/orders`

## Request parameters

### Query

- `begin_date` (string, required)
  Start date to filter orders by creation date (RFC 3339 format).

- `end_date` (string, required)
  End date for filtering orders by creation date (RFC 3339 format).

- `external_reference` (string, optional)
  It is an external reference of the order. It can be, for example, a hashcode from the Central Bank, functioning as an identifier of the transaction origin. This field must have a maximum of 64 characters and can only be numbers, letters, hyphens (-) and underscores (_). Special characters such as ([ ], (), '', @) are not allowed.

- `type` (string, optional)
  Order type, associated with the Mercado Pago solution for which it is created. For online card payments, the only possible value is "online".

- `status` (string, optional)
  Current status of the order.

- `status_detail` (string, optional)
  Details about payment status.

- `payment_method_id` (string, optional)
  Identifier of the payment method.

- `payment_method_type` (string, optional)
  Type of payment method.

- `page` (integer, optional)
  Page number for pagination. The minimum value is 1 page.

- `page_size` (integer, optional)
  Number of results per page. The maximum value is 100 results per page and, in case it is not filled, the default value is 20 results per page.

- `sort_by` (string, optional)
  Sorts the results by creation date or last update date (default: "created_date").

- `sort_order` (string, optional)
  Sorts the display of search results in descending order. The default value is "desc".

## Response parameters

- `data` (array, optional)
  List of orders matching the search criteria.

  - `data[].id` (string, optional)
  Identifier of the order, automatically generated by Mercado Pago.

  - `data[].type` (string, optional)
  Order type, associated with the Mercado Pago solution for which it is created. For online card payments, the only possible value is "online".
Possible enum values:

  - `online`
  Value associated with the creation of Orders for online payments.

  - `data[].processing_mode` (string, optional)
  Order processing mode
Possible enum values:

  - `manual`
  Order's processing will be made manually. It is the processing mode used for the "manual" option, as it sets the processing to be made afterwards, by using the 'Process order by ID' ("/v1/orders/{order_id}/process") endpoint.

  - `automatic`
  Order's processing will be made instantly. It is the capture mode used for the "automatic" option.

  - `data[].external_reference` (string, optional)
  It is an external reference of the order. It can be, for example, a hashcode from the Central Bank, functioning as an identifier of the transaction origin. This field must have a maximum of 150 characters and can only be numbers, letters, hyphens (-) and underscores (_). Special characters ([ ], (), '', @) are not allowed. Required only for PSE payments.

  - `data[].total_amount` (string, optional)
  Total amount to be paid.

  - `data[].total_paid_amount` (string, optional)
  Total amount to be paid, represents the sum of all the transaction's "paid_amount" values.

  - `data[].user_id` (string, optional)
  Identifier of the user to which the Mercado Pago application that created the order belongs. It is the person that will receive the payment.

  - `data[].status` (string, optional)
  Current status of the order.
Possible enum values:

  - `created`
  The order has been created successfully.

  - `processed`
  All transactions have been succesfully processed.

  - `action_required`
  Integrator action is required to complete processing. For example, the capture of an authorized payment.

  - `failed`
  An error occurred in the processing of the order. It may be due to sending incorrect data, risk of fraud, or rejections by the issuing entity of the payment method.

  - `processing`
  The order is being processed and does not require any action from the integrator. For example, the payment may be pending manual review.

  - `refunded`
  The order has been refunded.

  - `canceled`
  The order has been canceled.

  - `data[].status_detail` (string, optional)
  Details about payment status.
Possible enum values:

  - `accredited`
  Payment accredited.

  - `refunded`
  The payment has been refunded.

  - `partially_refunded`
  The payment has been partially refunded.

  - `waiting_capture`
  In cases of "status=action_required", integrator action is required to complete processing. This "status_detail" indicates that the capture of an authorized payment is needed.

  - `bad_filled_card_data`
  An error occurred in the processing due to sending incorrect card data.

  - `invalid_card_token`
  An error occurred in the processing due to sending an incorrect card token.

  - `high_risk`
  The transaction was rejected due to fraud prevention.

  - `rejected_by_issuer`
  The transaction failed because authorization was required.

  - `required_call_for_authorize`
  The transaction was rejected by the card issuer.

  - `max_attempts_exceeded`
  The transaction was rejected for exceeding the maximum number of attempts to complete it.

  - `card_disabled`
  The card chosen for the transaction is disabled.

  - `card_insufficient_amount`
  The card chosen for the transaction does not have enough founds.

  - `amount_limit_exceeded`
  The transaction amount exceeds the card limit.

  - `invalid_installments`
  There was an error during processing.

  - `processing_error`
  There was an error during processing.

  - `pending_review_manual`
  The payment is pending manual review.

  - `in_process`
  The payment is being processed.

  - `canceled`
  The order has been canceled.

  - `data[].capture_mode` (string, optional)
  Order capture mode.
Possible enum values:

  - `manual`
  Order's capture will be made manually. It allows the reservation of the transaction value in the payer's card, so the capture can be made afterwards, by using the 'Capture order' ("/v1/orders/{order_id}/capture") endpoint.

  - `automatic`
  Order's capture will be made automatically. Authorize and capture values at the same time.

  - `automatic_async`
  The order can be processed asynchronously. The order may remain in "status=processing" awaiting asynchronous update and the final status will be updated later through webhooks or queries.

  - `data[].currency` (string, optional)
  Identifier of the currency used in the order.

  - `data[].created_date` (string, optional)
  Order's creation date, in "yyyy-MM-ddTHH:mm:ss.sssZ" format.

  - `data[].last_updated_date` (string, optional)
  Order's last update date, in "yyyy-MM-ddTHH:mm:ss.sssZ" format.

  - `data[].integration_data` (object, optional)
  Additional information that can be used to integrate with other systems, such as the identifier of the order in the integrator's system.

  - `data[].integration_data.application_id` (string, optional)
  Identifier of the Mercado Pago application that created the order.

  - `data[].integration_data.integrator_id` (string, optional)
  Identifier of the integrator in Mercado Pago. It is the unique identifier of the integrator in Mercado Pago's systems.

  - `data[].integration_data.platform_id` (string, optional)
  Identifier of the platform in Mercado Pago. It is the unique identifier of the platform in Mercado Pago's systems.

  - `data[].integration_data.corporation_id` (string, optional)
  Identifier of the corporation in Mercado Pago. It is the unique identifier of the corporation in Mercado Pago's systems.

  - `data[].integration_data.sponsor` (object, optional)
  Identifier of the sponsor in Mercado Pago. It is the unique identifier of the sponsor in Mercado Pago's systems.

  - `data[].integration_data.sponsor.id` (string, optional)
  Identifier of the sponsor in Mercado Pago. It is the unique identifier of the sponsor in Mercado Pago's systems.

  - `data[].transactions` (object, optional)
  Contains information about the transactions associated with the order.

  - `data[].transactions.payments` (array, optional)
  Contains information about the payment associated with the order.

  - `data[].transactions.payments[].id` (string, optional)
  Identifier of the payment transaction, automatically generated.

  - `data[].transactions.payments[].amount` (string, optional)
  Transaction amount.

  - `data[].transactions.payments[].paid_amount` (string, optional)
  Transaction paid amount. Represents the real amount paid including discounts or tips.

  - `data[].transactions.payments[].reference_id` (string, optional)
  Reference ID of the transaction.

  - `data[].transactions.payments[].status` (string, optional)
  Payment status.

  - `data[].transactions.payments[].status_detail` (string, optional)
  Details about payment status.

  - `data[].transactions.payments[].payment_method` (object, optional)
  Information about the payment method.

  - `data[].transactions.payments[].payment_method.id` (string, optional)
  Identifier of the payment method.

  - `data[].transactions.payments[].payment_method.type` (string, optional)
  Type of payment method.

  - `data[].transactions.payments[].payment_method.installments` (integer, optional)
  Number of installments.

  - `data[].transactions.payments[].payment_method.transaction_security` (object, optional)
  Transaction security configuration for 3DS (3D Secure), an authentication protocol used in online transactions with card. After creating the order, the response will indicate if the challenge is required. If not required, the "status" field will have the value "processed", allowing you to continue normally with the application flow. If the challenge is required, the order will be returned with "status=action_required", "status_detail=pending_challenge" and the challenge URL will be available in the "url" field. The challenge must be displayed in an iframe using the URL returned, allowing the buyer to complete authentication without leaving the checkout flow. The buyer has 40 minutes to complete the challenge from when the URL is created. If not completed within this period, the bank will reject the transaction and Mercado Pago will consider the payment expired.

  - `data[].transactions.payments[].payment_method.transaction_security.validation` (string, optional)
  Defines when the 3DS (3D Secure) flow should be executed.
Possible enum values:

  - `on_fraud_risk`
  3DS (3D Secure) is required according to transaction risk. Recommended to balance security and transaction approval.

  - `never`
  The 3DS (3D Secure) flow and challenge are never executed. This is the default value if the field is not sent.

  - `data[].transactions.payments[].payment_method.transaction_security.liability_shift` (string, optional)
  Defines the financial responsibility in case of dispute. Should not be sent when "validation" is "never".
Possible enum values:

  - `required`
  The financial responsibility in case of dispute is of the card brand. This is the only value accepted for 3DS (3D Secure).

  - `data[].transactions.payments[].payment_method.transaction_security.url` (string, optional)
  URL of the challenge displayed after creating an order returned with "status=action_required" and "status_detail=pending_challenge". The challenge must be displayed in an iframe using the returned URL, allowing the buyer to complete authentication without leaving the checkout flow. The buyer has 40 minutes to complete the challenge from when the URL is created. If not completed within this period, the bank will reject the transaction and Mercado Pago will consider the payment expired.

  - `data[].transactions.payments[].payment_method.transaction_security.id` (string, optional)
  ID of the challenge of the 3DS (3D Secure) security protocol.

  - `data[].transactions.payments[].payment_method.transaction_security.type` (string, optional)
  Type of challenge. In the case of 3DS (3D Secure), the only possible value is "three_ds".

  - `data[].transactions.payments[].payment_method.transaction_security.status` (string, optional)
  Status of the challenge in the 3DS (3D Secure) security protocol.
Possible enum values:

  - `AUTHENTICATED`
  Authentication performed by the responsible bank and forwarded to card brand validation.

  - `NOT_AUTHENTICATED`
  The challenge was not performed correctly or the responsible bank did not authorize the transaction due to some possible risk.

  - `CHALLENGE`
  The bank requested a challenge from the buyer and it has not yet been completed.

  - `ATTEMPTED`
  Authentication performed by the card brand.

  - `REJECTED`
  The responsible bank rejected the authentication due to some possible risk and also denied the possibility of challenge.

  - `ERROR`
  Missing some information required for 3DS authentication. Example: the "device_id" field was not filled.

- `paging` (object, optional)
  Pagination information.

  - `paging.total` (string, optional)
  Total number of orders matching the search criteria.

  - `paging.total_pages` (string, optional)
  Total number of pages available.

  - `paging.offset` (string, optional)
  Number of items skipped.

  - `paging.limit` (string, optional)
  Maximum number of items returned per page.

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | missing_required_params | The "begin_date" and "end_date" parameters are missing. These parameters are mandatory for the search. |
| 400 | invalid_parameter | An invalid value was sent for a query parameter. This can occur with invalid date formats (must use RFC3339 format, e.g.: "2023-01-01T00:00:00Z"), invalid pagination values ("page" e "page_size"), invalid sorting values ("sort_by", "sort_order") or invalid filter values ("status", "type", "payment_method_id", etc.). Check the error message details for specific information. |
| 401 | 401 | The value sent as Access Token is incorrect. Please check and try again with the correct value. |
| 401 | invalid_credentials | There is no support for test credentials. Use test users with production credentials for the sandbox environment and your production credentials for the production environment. |
| 500 | internal_error | Generic error. Please try submitting the request again. |

## Request example

### cURL

```bash
curl -X GET \
  'https://api.mercadopago.com/v1/orders?begin_date=<BEGIN_DATE>&end_date=<END_DATE>&external_reference=<EXTERNAL_REFERENCE>&type=<TYPE>&status=<STATUS>&status_detail=<STATUS_DETAIL>&payment_method_id=<PAYMENT_METHOD_ID>&payment_method_type=<PAYMENT_METHOD_TYPE>&page=<PAGE>&page_size=<PAGE_SIZE>&sort_by=<SORT_BY>&sort_order=<SORT_ORDER>' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
```

## Response example

```json
{
  "data": [
  {
  "id": "ORD01K9SN1Q5959CGN8QGW00EH7V5",
  "type": "online",
  "processing_mode": "automatic",
  "external_reference": "ext_ref_1234",
  "total_amount": "50.00",
  "total_paid_amount": "50.00",
  "user_id": "12345",
  "status": "processed",
  "status_detail": "accredited",
  "capture_mode": "automatic",
  "currency": "COP",
  "created_date": "2024-08-26T13:06:51.045317772Z",
  "last_updated_date": "2024-08-26T13:06:51.045317772Z",
  "integration_data": {
  "application_id": "1234",
  "integrator_id": "dev_123",
  "platform_id": "1234567890",
  "corporation_id": "string",
  "sponsor": {
  "id": null
  }
  },
  "transactions": {
  "payments": [
  null
  ]
  }
  }
  ],
  "paging": {
  "total": "54",
  "total_pages": "3",
  "offset": "0",
  "limit": "20"
  }
}
```