---
title: "List orders"
method: GET
path: "/api/oms/pvt/orders"
tags: ["Orders"]
---

# List orders

`GET /api/oms/pvt/orders`

Retrieves a list of orders according to the filters described below. 

>⚠️ **B2B Buyer Portal** 
>
> When filtering by [contact information fields](https://developers.vtex.com/docs/api-reference/b2b-contact-information-api#post-/api/dataentities/contact_information/documents), you must use the exact value of the field in the contact information. Partial matches are not supported. 

The limit of information retrieval is 30 pages, the default number of orders per page is 15 and it is possible to configure it up to 100 using the `per_page` parameter. 

Be aware that since October 3rd, 2018, this endpoint does not return the `items` property. 

> You can only access information from orders created in the last two years, and that same period is valid for customers through [My Account](https://help.vtex.com/en/tutorial/how-my-account-works--2BQ3GiqhqGJTXsWVuio3Xh). 

> This endpoint should **not** be used for integrations. Use the [orders Feed or hook](https://developers.vtex.com/docs/guides/orders-feed) for this purpose. 

This endpoint returns only orders that already have been indexed, which takes approximately four minutes. Because of this, the data retrieved may present inconsistencies. To get live up-to-date information and [build order integrations](https://developers.vtex.com/vtex-rest-api/docs/erp-integration-set-up-order-integration) use the [orders Feed or hook](https://developers.vtex.com/docs/guides/orders-feed).

> **Onboarding guide** 
>
> Check the new [Orders onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/orders-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Orders and is organized by focusing on the developer's journey. 

## Permissions

Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:

| **Product** | **Category** | **Resource** |
| --------------- | ----------------- | ----------------- |
| OMS | OMS access | **List Orders** |
| Checkout         | CheckoutResources | **Orders Full Access** |

You can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):

| **Role** | **Resource** | 
| --------------- | ----------------- | 
| OMS - Full access | List Orders |
| Checkout Admin | List Orders |
| IntegrationProfile - Fulfillment Oms | List Orders |
| OMS - Full access | Orders Full Access |
| Checkout Admin | Orders Full Access |
| IntegrationProfile - Fulfillment Oms | Orders Full Access |

>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm). 

To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

## Query parameters

- `orderBy` string
- `page` integer
- `per_page` integer
- `f_hasInputInvoice` boolean
- `q` string
- `f_shippingEstimate` string
- `f_invoicedDate` string
- `f_creationDate` string
- `f_authorizedDate` string
- `f_UtmSource` string
- `f_sellerNames` string
- `f_callCenterOperatorName` string
- `f_salesChannel` string
- `salesChannelId` string
- `f_affiliateId` string
- `f_status` string
- `incompleteOrders` boolean
- `f_paymentNames` string
- `f_RnB` string
- `searchField` string
- `f_isInstore` boolean

## Headers

- `Accept` string, required
- `Content-Type` string, required

## Response `200`

OK

---

[API](https://skmtc.net/vtex/apis/orders-api.md) · [All operations](https://skmtc.net/vtex/apis/orders-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vtex/orders-api/revisions/ea03e98721e5/schema)