Orders API
Each purchase a customer makes in your store generates an order on VTEX. With the Orders API, you can view orders statuses and manage multiple aspects involved in order fulfillment, such as financial transactions, invoicing, shipping, and subscriptions. You can also modify orders and make configurations to allow or forbid marketplaces and sellers to change or cancel orders.
Order integration
To automate actions related to order processing, you can integrate orders with systems like ERP (Enterprise Resource Planning) and WMS (Warehouse Management System) using Feed and Hook.
Common parameters
| Parameter name | Description | Type |
|---|---|---|
{{accountName}} |
Name of the VTEX account. Used as part of the URL. | Server variable. |
{{environment}} |
Environment to use. Used as part of the URL. The default value is vtexcommercestable. |
Server variable. |
X-VTEX-API-AppKey |
Unique identifier of the API key. | Authentication header. Must be used together with X-VTEX-API-AppToken. Not necessary when using VtexIdclientAutCookie. |
X-VTEX-API-AppToken |
Secret token of the API key. | Authentication header. Must be used together with X-VTEX-API-AppKey. Not necessary when using VtexIdclientAutCookie. |
VtexIdclientAutCookie |
User token, valid for 24 hours. | Authentication header. Not necessary when using X-VTEX-API-AppKey and X-VTEX-API-AppToken. |
Endpoints
Orders
| Summary | Method | Path |
|---|---|---|
| Get order | GET | /api/oms/pvt/orders/{orderId} |
| Get orders by order group ID | GET | /api/oms/pvt/orders/order-group/{orderGroup} |
| List orders | GET | /api/oms/pvt/orders |
| Start handling order | POST | /api/oms/pvt/orders/{orderId}/start-handling |
| Cancel order | POST | /api/oms/pvt/orders/{orderId}/cancel |
| Register modifications on order | POST | /api/oms/pvt/orders/{orderId}/changes |
| Add log in orders | POST | /api/oms/pvt/orders/{orderId}/interactions |
Order modifications
| Summary | Method | Path |
|---|---|---|
| Get order modifications summary | GET | /api/orders/pvt/document/{orderId}/change-summary |
| Create order modifications | PATCH | /api/order-system/orders/{changeOrderId}/changes |
| Get order modifications history | GET | /api/order-system/orders/{changeOrderId}/changes |
| Get order modifications details | GET | /api/order-system/orders/{changeOrderId}/changes/{changeRequestId} |
| Preview order modifications | POST | /api/order-system/orders/{changeOrderId}/changes/preview |
| Retry order modifications | POST | /api/order-system/orders/{changeOrderId}/changes/{changeRequestId}/retry |
| Cancel order modifications | POST | /api/order-system/orders/{changeOrderId}/changes/{changeRequestId}/cancel |
| Update Order modifications settings | PUT | /api/order-system/orders/changes/settings |
| Get Order modifications settings | GET | /api/order-system/orders/changes/settings |
Invoice
| Summary | Method | Path |
|---|---|---|
| Order invoice notification | POST | /api/oms/pvt/orders/{orderId}/invoice |
| Update order's partial invoice (send tracking number) | PATCH | /api/oms/pvt/orders/{orderId}/invoice/{invoiceNumber} |
Tracking
| Summary | Method | Path |
|---|---|---|
| Update order tracking status | PUT | /api/oms/pvt/orders/{orderId}/invoice/{invoiceNumber}/tracking |
Conversation
| Summary | Method | Path |
|---|---|---|
| Retrieve order conversation | GET | /api/oms/pvt/orders/{orderId}/conversation-message |
Payment
| Summary | Method | Path |
|---|---|---|
| Retrieve payment transaction | GET | /api/oms/pvt/orders/{orderId}/payment-transaction |
| Send payment notification | POST | /api/oms/pvt/orders/{orderId}/payments/{paymentId}/payment-notification |
Feed v2 (deprecated)
| Summary | Method | Path |
|---|---|---|
| Get feed order status | GET | /api/oms/pvt/feed/orders/status |
Feed v3
| Summary | Method | Path |
|---|---|---|
| Get feed configuration | GET | /api/orders/feed/config |
| Create or update feed configuration | POST | /api/orders/feed/config |
| Delete feed configuration | DELETE | /api/orders/feed/config |
| Retrieve feed items | GET | /api/orders/feed |
| Commit feed items | POST | /api/orders/feed |
| Test JSONata expression | POST | /api/orders/expressions/jsonata |
Order hook
| Summary | Method | Path |
|---|---|---|
| Get hook configuration | GET | /api/orders/hook/config |
| Create or update hook configuration | POST | /api/orders/hook/config |
| Delete hook configuration | DELETE | /api/orders/hook/config |
User orders
| Summary | Method | Path |
|---|---|---|
| Retrieve user's orders | GET | /api/oms/user/orders |
| Retrieve user order details | GET | /api/oms/user/orders/{orderId} |
Change seller
| Summary | Method | Path |
|---|---|---|
| Get window to change seller | GET | /api/checkout/pvt/configuration/window-to-change-seller |
| Update window to change seller | POST | /api/checkout/pvt/configuration/window-to-change-seller |