Retrieve user's orders
Lists all orders.
You can only access information from orders created in the last two years, and that same period is valid for customers through My Account.
B2C orders
You can use this endpoint to list all orders from a given customer, filtering by their email.
B2B Buyer Portal orders
You can use this endpoint to list orders by filtering with the following fields:
-
Text: texts in existing order fields, custom fields, and contact information fields.
-
Status: the current status of the orders you wish to list.
-
Creation date: the date the order was created.
-
The purchase agent ID: ID of the purchase agent that made the order.
-
Pending approval: You can also filter by orders which are pending approval (true) or orders which are not pending approval (false).
⚠️ When using the text field to filter by contact information, you must use the exact value of the field in the contact information. Partial matches are not supported. For example: If the user's first name is set to John Henry, you must write John Henry in the text field. Searching for John will return orders made by John, and not John Henry.
Note that this request should be made by an user or an appKey / appToken pair that is associated with the Call center operator role. Otherwise, it will return only orders from the same email informed in the clientEmail query parameter.
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 | View order |
| View My Contract Orders | My Account / OMS | ViewMyContractOrders |
| View My Org Unit Orders | My Account / OMS | ViewMyOrgUnitOrders |
You can create a custom role with that resource or use one of the following predefined roles:
| Role | Resource |
|---|---|
| Call center operator | View order |
| OMS - Read only | View order |
❗ Assigning a predefined role to users or API 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 API keys. To learn more about machine authentication at VTEX, see Authentication overview.
Query parameters
Customer email. This field is exclusive for B2C users.
Page number for result pagination.
Page quantity for result pagination.
Filter by text in existing order fields, custom fields, and contact information fields. This field is exclusive for B2B Buyer Portal users.
Order status. You can provide multiple values by repeating the query parameter. For example:
- status=payment-pending&status=handling
This field is exclusive for B2B Buyer Portal users.
You can filter orders by creation date by concatenating the sufix creationDate with the range date in Timestamp format. This field accepts the value * for open ranges. For example:
- creationDate:[* TO 2025-04-08T23:59:59.999Z]
- creationDate:[2025-01-01T02:00:00.000Z TO *]
This field is exclusive for B2B Buyer Portal users.
ID of the purchase agent. You can provide multiple values by repeating the query parameter. For example:
- purchase_agent_id=848a994a-1b6b-4dbd-5555-0455af24e0f2&purchase_agent_id=848a994a-1b6b-4444-8498-0455af24e0f2
This field is exclusive for B2B Buyer Portal users.
You can filter orders that are pending approval by the current user or by an organizational unit associated with the current user if it has ViewMyOrgUnitOrders permission. This field is exclusive for B2B Buyer Portal users.
Headers
Type of the content being sent.
HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
Response
OK
Example response
{
"list": [
{
"orderId": "1172452900788-01",
"creationDate": "2019-01-28T20:09:43+00:00",
"clientName": "Cunha VTEX",
"items": [
{
"seller": "1",
"quantity": 1,
"description": "Reservoir hose",
"ean": null,
"refId": "TE3121110",
"id": "195",
"productId": "134",
"sellingPrice": 7390,
"price": 7390
},
{
"seller": "1",
"quantity": 1,
"description": "Reservoir filter",
"ean": null,
"refId": "XC459N610CA",
"id": "238",
"productId": "162",
"sellingPrice": 5190,
"price": 5190
}
],
"totalValue": 1160,
"paymentNames": "Boleto Bancário",
"status": "handling",
"statusDescription": "Preparing for delivery",
"marketPlaceOrderId": null,
"sequence": "502556",
"salesChannel": "1",
"affiliateId": "GTB",
"origin": "Marketplace",
"workflowInErrorState": false,
"workflowInRetry": false,
"lastMessageUnread": " Lux Store Seu pedido foi alterado! Pedido realizado em: 28/01/2019 Olá, Rodrigo. Seu pedido foi alterado. Seguem informações abaixo: ",
"ShippingEstimatedDate": "2019-02-04T20:33:46+00:00",
"ShippingEstimatedDateMax": null,
"ShippingEstimatedDateMin": null,
"orderIsComplete": true,
"listId": null,
"listType": null,
"authorizedDate": "2019-01-28T20:33:04+00:00",
"callCenterOperatorName": null,
"totalItems": 1,
"currencyCode": "BRL"
}
],
"stats": {
"stats": {
"totalValue": {
"Count": 19,
"Max": 0,
"Mean": 0,
"Min": 0,
"Missing": 0,
"StdDev": 0,
"Sum": 0,
"SumOfSquares": 0,
"Facets": {}
},
"totalItems": {
"Count": 19,
"Max": 0,
"Mean": 0,
"Min": 0,
"Missing": 0,
"StdDev": 0,
"Sum": 0,
"SumOfSquares": 0,
"Facets": {}
}
}
}
}