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

> Check the [Orders onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/orders-overview) for a journey-based overview of the Orders documentation available in the Developer Portal. 

## 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

## Changes

- **2026-08-07** `619168717f2e` — 6 breaking, 2 info
  - the response property `list/items/currencyCode` became nullable for the status `200`
  - the response property `list/items/paymentNames` became nullable for the status `200`
  - removed the required property `stats/stats/totalItems/Facets/currencyCode` from the response with the `200` status
  - removed the required property `stats/stats/totalItems/Facets/origin` from the response with the `200` status
  - …4 more

[Change history](https://skmtc.dev/vtex/apis/orders-api/changes/api/oms/pvt/orders/get.md)

---

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