v60

latestOpenAPI 3.0.0raw.githubusercontent.com2026-08-01361201.5 MB

Orders

Get orders by order group ID

Retrieves details about all orders related to the same purchase by searching by order group ID.

⚠️ Throttling: Each VTEX account can make up to 6000 requests per minute.

You can only access information from orders created in the last two years, and that same period is valid for customers through My Account.

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
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	View order
Checkout Admin	View order
IntegrationProfile - Fulfillment Oms	View order
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.

get/api/oms/pvt/orders/order-group/{orderGroup}

Path parameters

orderGroupstring required

Example:v71021570str

Order group ID is a part of the order ID that groups all orders related to the same purchase. For example, when an order is fullfilled by multiple sellers, each seller has its own order ID (v71021570str-01 and v71021570str-02), but they share the same order group ID (v71021570str).

Headers

Acceptstring required

Example:application/json

HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.

Content-Typestring required

Example:application/json

Type of the content being sent.

Response

orderIdstring

Order ID.

sequencestring

Sequence number part of the order ID. For example, in order v70530116str-01, the sequence is 70530116.

marketplaceOrderIdstring nullable

Order ID in the marketplace.

marketplaceServicesEndpointstring nullable

Marketplace endpoint for post purchase communication.

sellerOrderIdstring

Seller order ID.

origin'Marketplace' | 'Fulfillment' | 'Chain'

Order's origin in the order flow.

affiliateIdstring nullable

Three-letter affiliate code configured by the seller to identify a marketplace.

salesChannelstring

Sales channel (or trade policy) ID related to the order.

merchantNamestring nullable

For a VTEX store, the merchant's name will be the same as the account name. An external seller can have a merchantName, but it will not be an account name.

statusstring

Order status in the workflow.

statusDescriptionstring nullable

Status description displayed on the VTEX Admin. This field is obsolete and may not return any value.

valueinteger

Order total value in cents.

creationDatestring

Order creation date in ISO 8601 time zone offset format, as in YYYY-MM-DDThh:mm:ssZ.

lastChangestring

Order last change date in ISO 8601 time zone offset format, as in YYYY-MM-DDThh:mm:ssZ.

orderGroupstring

Order group ID, a segment of the order ID that groups all orders related to the same purchase. For example, in order ID v71021570str-02), the order group ID is v71021570str.

marketplaceItemsstring[]

Array with marketplace items information.

followUpEmailstring

Email of the store employee responsible for managing the order.

lastMessagestring nullable

Last transactional message sent to the customer.

hostnamestring

Main account name.

openTextFieldobject nullable

Optional field for additional information.

roundingErrorinteger

Rounding error total value in cents, when applicable. For example, in orders with a discount over non-integer multiplier items, the rounding price is applied per item, not after the sum of all items, what can cause a difference in the total discount value.

orderFormIdstring

ID of the orderForm, the main object processed by the VTEX Checkout.

commercialConditionDatastring nullable

Commercial condition information.

isCompletedboolean

Defines if the order payment has been settled (true) or not (false).

allowCancellationboolean

Defines if order cancellation is allowed (true) or not anymore (false).

allowEditionboolean

Defines if the order can be edited (true) or not anymore (false).

isCheckedInboolean

Defines if the order was placed via VTEX Sales App (true) or not (false).

authorizedDatestring nullable

Order authorization date in ISO 8601 time zone offset format, as in YYYY-MM-DDThh:mm:ssZ.

invoicedDatestring nullable

Order invoice date in ISO 8601 time zone offset format, as in YYYY-MM-DDThh:mm:ssZ.

cancelReasonstring nullable

Order cancellation reason.

checkedInPickupPointIdstring nullable

When the order is created at a physical store which is configured as a pickup point, this field retrieves the pickup point ID.