List orders
Retrieves a list of orders according to the filters described below.
⚠️ B2B Buyer Portal
When filtering by contact information fields, 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.
This endpoint should not be used for integrations. Use the orders Feed or hook 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 use the orders Feed or hook.
Onboarding guide
Check the new Orders onboarding guide. 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 must have at least one of the appropriate License Manager resources 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 with that resource or use one of the following predefined roles:
| 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 to users or application keys usually grants permission to multiple License Manager resources. 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.
To learn more about machine authentication at VTEX, see Authentication overview.
Query parameters
You can retrieve orders lists filtering by an OrderField combined with an OrderType. To do so, you have to concatenate them: orderBy={{OrderField}},{{OrderType}}.
- OrderField values accepted: creationDate, orderId, items, totalValue and origin.
- OrderType values accepted: asc and desc.
Define the number of pages you wish to retrieve, restricted to the limit of 30 pages.
Quantity of orders for each page, the default value is 15 and it goes up to 100 orders per page. Be aware that the limit of retrieval ofthis endpoint is 30 pages.
Filters list to return only orders with non null values for the invoiceInput field.
This parameter filters using Fulltext and accepts the values below. Be aware that the + caracter is not allowed in Fulltext Search.
- Order Id
- Client email
- Client document
- Client name
B2B Buyer Portal users can search for contact information fields, which includes the values below:
- User email.
- User first name.
- User last name.
- User phone number.
- User document ID.
- User document type.
You can filter orders by shipping estimate time in days by concatenating the desired number of days with the sufix .days. For example:
- Next 7 days: 7.days
- Tomorrow: 1.days
- Today: 0.days
- Late: -1.days
You can filter orders by invoiced date by concatenating the sufix invoicedDate: with the range date in Timestamp format. For example:
- 1 Day: invoicedDate:[2022-01-01T02:00:00.000Z TO 2022-01-02T01:59:59.999Z]
- 1 Month: invoicedDate:[2022-01-01T02:00:00.000Z TO 2022-02-01T01:59:59.999Z]
- 1 Year: invoicedDate:[2022-01-01T02:00:00.000Z TO 2022-01-01T01:59:59.999Z]
You can filter orders by creation date by concatenating the sufix creationDate: with the range date in Timestamp format. For example:
- 1 Day: creationDate:[2022-01-01T02:00:00.000Z TO 2022-01-02T01:59:59.999Z]
- 1 Month: creationDate:[2022-01-01T02:00:00.000Z TO 2022-02-01T01:59:59.999Z]
- 1 Year: creationDate:[2022-01-01T02:00:00.000Z TO 2022-01-01T01:59:59.999Z]
You can filter orders by creation date by concatenating the sufix authorizedDate: with the range date in Timestamp format. For example:
- 1 Day: authorizedDate:[2022-01-01T02:00:00.000Z TO 2022-01-02T01:59:59.999Z]
- 1 Month: authorizedDate:[2022-01-01T02:00:00.000Z TO 2022-02-01T01:59:59.999Z]
- 1 Year: authorizedDate:[2022-01-01T02:00:00.000Z TO 2022-01-01T01:59:59.999Z]
You can filter orders by Urchin Tracking Module (UTM) source.
You can filter orders by using a seller's name.
You can filter orders by using a Call Center Operator's identification.
You can filter orders by sales channel's (or trade policy) name.
You can filter orders by sales channel's (or trade policy) ID.
You can filter orders by affiliate ID.
You can filter orders by the following order status:
- waiting-for-sellers-confirmation
- payment-pending
- payment-approved
- ready-for-handling
- handling
- invoiced
- canceled
When set as true, you retrieve incomplete orders, when set as false, you retrieve orders that are not incomplete.
You can filter orders by payment type.
You can filter orders by rates and benefits (promotions).
You can search orders by using one of the following criterias:
- SKU ID - sku_Ids&sku_Ids
- Gift List ID - listId&listId
- Transaction ID (TID) - tid&tid
- PCI Connector's Transaction ID (TID) - pci_tid&pci_tid
- Payment ID (PID) - paymentId&paymentId
- Connector's NSU - nsu&nsu
When set as true, this parameter filters orders made via inStore, and when set as false, it filters orders that were not made via inStore.
Headers
HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
Type of the content being sent.
Response
OK