---
title: "Retrieve user's orders"
method: GET
path: "/api/oms/user/orders"
tags: ["User orders"]
---

# Retrieve user's orders

`GET /api/oms/user/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](https://help.vtex.com/en/tutorial/how-my-account-works--2BQ3GiqhqGJTXsWVuio3Xh). 

 ## 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](https://developers.vtex.com/docs/guides/custom-fields-integration), and [contact information fields](https://developers.vtex.com/docs/api-reference/b2b-contact-information-api#post-/api/dataentities/contact_information/documents). 

 - 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](https://developers.vtex.com/docs/guides/user-authentication-and-login) or [an appKey / appToken pair](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) that is associated with the [Call center operator](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy#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](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 | **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](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** | 
| --------------- | ----------------- | 
| Call center operator | View order |
| OMS - Read only | View order |

>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or API 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 API 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

- `clientEmail` string
- `page` string
- `per_page` string
- `text` string
- `status` string
- `creation_date` string
- `purchase_agent_id` string
- `my_pending_approvals` boolean

## Headers

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

## Response `200`

OK

- Userorderslist — Order list object.
  - `list` List1[], required — List with user's orders details.
    - `orderId` string, required — Order ID is a unique code that identifies an order.
    - `creationDate` string, required — Order's creation date.
    - `clientName` string, required — Order's customer name.
    - `items` Item2[], nullable, required — Information about order's items.
      - `seller` string, required — Seller related to the order.
      - `quantity` integer, required — Quantity of SKUs.
      - `description` string, required — Description of items.
      - `ean` string, nullable, required — EAN of the SKU.
      - `refId` string, nullable, required — Item's reference ID.
      - `id` string, required — Item's SKU ID, which is a unique numerical identifier.
      - `productId` string, required — ID of the Product associated with the item.
      - `sellingPrice` integer, required — Details on item's selling price.
      - `price` integer, required — Item's price.
    - `totalValue` integer, required — Total value amount.
    - `paymentNames` string, nullable, required — Payment system name.
    - `status` string, required — Order [status](https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials_196).
    - `statusDescription` string, required — Status description which is displayed on the Admin panel. This field is deprecated and may not return any value.
    - `marketPlaceOrderId` string, nullable, required — Marketplace order ID.
    - `sequence` string, required — Six-digit string that follows the order ID. For example, in order `1268540501456-01 (501456)`, the sequence is `501456`.
    - `salesChannel` string, required — Sales channel (or [trade policy](https://help.vtex.com/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) ID related to the order.
    - `affiliateId` string, required — Corresponds to the three-digits [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187) identification code of the seller responsible for the order.
    - `origin` string, required — Order's [origin in the order flow](https://developers.vtex.com/docs/guides/orders-overview#understanding-order-flow-types), which can be `Marketplace`, `Fulfillment` or `Chain`.
    - `workflowInErrorState` boolean, required — If there is a work flow error (`true`) or not (`false`).
    - `workflowInRetry` boolean, required — If the order is in a work flow retry (`true`) or not (`false`).
    - `lastMessageUnread` string, nullable, required — Last sent transactional message.
    - `ShippingEstimatedDate` string, nullable, required — Estimate shipping date.
    - `ShippingEstimatedDateMax` string, nullable, required — The most extended shipping estimation possible.
    - `ShippingEstimatedDateMin` string, nullable, required — The least extended shipping estimation possible.
    - `orderIsComplete` boolean, required — If it is a completed order (`true`) or not (`false`). For more information, see [Order flow and status](https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials_196).
    - `listId` string, nullable, required — Related Gift List ID.
    - `listType` string, nullable, required — Related Gift list type.
    - `authorizedDate` string, nullable, required — Authorized order date.
    - `callCenterOperatorName` string, nullable, required — Call center operator responsible for the order.
    - `totalItems` integer, required — Order's total amount of items.
    - `currencyCode` string, nullable, required — Currency code in ISO 4217. For example, `BRL`.
  - `facets` string[], required — Array containing facets information.
  - `paging` Paging, required — Pagination information.
    - `total` integer, required — Total number of orders.
    - `pages` integer, required — Total number of pages.
    - `currentPage` integer, required — Number of the current page.
    - `perPage` integer, required — Number of orders per page.
  - `stats` Stats2, required
    - `stats` Stats3, required
      - `totalValue` TotalValue1, required
        - `Count` integer, required
        - `Max` integer, required
        - `Mean` integer, required
        - `Min` integer, required
        - `Missing` integer, required
        - `StdDev` integer, required
        - `Sum` integer, required
        - `SumOfSquares` integer, required
        - `Facets` object, required
      - `totalItems` TotalItems1, required
        - `Count` integer, required
        - `Max` integer, required
        - `Mean` integer, required
        - `Min` integer, required
        - `Missing` integer, required
        - `StdDev` integer, required
        - `Sum` integer, required
        - `SumOfSquares` integer, required
        - `Facets` object, required

---

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