VTEX

Orders API

>Check the new [Orders onboarding guide](https://developers.vtex.com/docs/guides/orders-overview). We created this guide to improve the onboarding experience…

Other#openapi

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

>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.

Receive, process, and manage every order in your store through our Order Management API.

Endpoints 28

Orders

  • GETList orders/api/oms/pvt/orders?orderBy=v502556llux-01,asc&page=10&per_page=15&f_creationDate=creationDate:[2016-01-01T02:00:00.000Z TO 2021-01-01T01:59:59.999Z]&f_hasInputInvoice=false&q=- OrderID: v212333lux-02 - Client email: taylor@email.com - Client document: 21133355524 - Client name: Taylor&utc=-2000&f_shippingEstimate=0.days&f_invoicedDate=invoicedDate:[2022-01-01T02:00:00.000Z TO 2022-01-02T01:59:59.999Z]&f_authorizedDate=creationDate:[2022-01-01T02:00:00.000Z TO 2022-01-02T01:59:59.999Z]&f_UtmSource=christmas_campaign&f_sellerNames=SellerName&f_callCenterOperatorName=Operator%20Name&f_salesChannel=Main&salesChannelId=1&f_affiliateId=WLM&f_status=ready-for-handling&incompleteOrders=true&f_paymentNames=Visa&f_RnB=Free+Shipping&searchField= - SKU ID: `25` - Gift List ID: `11223` - Transaction ID (TID): `54546300238810034995829230012` - PCI Connector's Transaction ID (TID): `7032909234899834298423209` - Payment ID (PID): `2` - Connector's NSU: `2437281`&f_isInstore=trueRetrieves a list of orders according to the filters described below. The limit of information retrieval is 30 pages, the default number of orders per page is…
  • GETGet order/api/oms/pvt/orders/:orderIdThis endpoint retrieves order details by searching a specific order ID or sequence number. > The View order resource is needed to use this API request. This…
  • POSTCancel order/api/oms/pvt/orders/:orderId/cancelYou should use this endpoint to cancel an order by its order identification number (the orderId). A common scenario is one where the seller has a problem with…
  • POSTRegister change on order/api/oms/pvt/orders/:orderId/changes> Timeout settings > > This is a synchronous API, which means the application requests data and waits until a value is returned. This behavior can cause…
  • POSTAdd log in orders/api/oms/pvt/orders/:orderId/interactionsAdd a Log in Interactions Order Array.
  • POSTStart handling order/api/oms/pvt/orders/:orderId/start-handlingChanges the status of an order to indicate that it is in handling. > Expect a status 204 response with no content in case of a successful request. The store…

Invoice

  • POSTOrder invoice notification/api/oms/pvt/orders/:orderId/invoiceEntering the invoice in the order is a required step for its status to change to Invoiced - a sign that the order has been successfully completed. Remember…
  • PATCHUpdate order's partial invoice (send tracking number)/api/oms/pvt/orders/:orderId/invoice/:invoiceNumberUpdate a given order, adding its tracking number to its Partial invoice. After using this call to add a tracking number to an order, you can use the Update…

Tracking

  • PUTUpdate order tracking status/api/oms/pvt/orders/:orderId/invoice/:invoiceNumber/trackingThis endpoint sends a tracking event to an order that already has a tracking number registered to its invoice. This request is not meant to send tracking…

Conversation

  • GETRetrieve order conversation/api/oms/pvt/orders/:orderId/conversation-message?reason=data-validationList all order conversations of an order by its order ID.

Payment

  • GETRetrieve payment transaction/api/oms/pvt/orders/:orderId/payment-transactionRetrieves transaction details by order ID. All events in the transaction will be registered in this call's response body. In scenarios of order changes, it is…
  • POSTSend payment notification/api/oms/pvt/orders/:orderId/payments/:paymentId/payment-notificationSend a payment notification of a given order, by order ID. > The Notify payment resource is needed to use this API request. This is included in OMS - Full…

Feed v3

  • POSTTest JSONata expression/api/orders/expressions/jsonataThis endpoint allows you to test a JSON document with a JSONata expression, returning true if the document meets the criteria posed in the expression, or…
  • GETRetrieve feed items/api/orders/feed?maxlot={{maxLot}}Retrieve items from feed queue. The event will be removed if the message send retry is equal to, or greater than the maximum retention period. > This API will…
  • POSTCommit feed items/api/orders/feedCommit items in the feed queue.
  • GETGet feed configuration/api/orders/feed/configThe Orders Feed v3 is the best way to create order integrations. Below you can find details on the configuration API specification, and to know more see our…
  • POSTCreate or update feed configuration/api/orders/feed/configThe Orders Feed v3 is the best way to create order integrations. Below you can find details on the configuration API specification, and to know more see our…
  • DELETEDelete feed configuration/api/orders/feed/configDeletes the configuration set up in Feed v3.

Order hook

  • GETGet hook configuration/api/orders/hook/config?clientEmail=customer@mail.com&page=10&per_page=15Retrieves a given hook's configuration details. Learn more with the orders hook guide. > 📘 Onboarding guide > > Check the new Orders onboarding guide. We…
  • POSTCreate or update hook configuration/api/orders/hook/configConfigures filtering rules applied to orders hook. Learn more with the orders hook guide. There are two types of filtering that can be used: FromWorkflow:…
  • DELETEDelete hook configuration/api/orders/hook/configDeletes a given hook configuration. Learn more with the orders hook guide.

Export order report

  • GETExport order report with status 'Completed'/api/oms/pvt/admin/reports/completedRetrieves a list of all order reports that are completed, by accountName. Be aware that the scope of the export log is per user. > This endpoint is for VTEX…
  • GETExport order report with status 'In Progress'/api/oms/pvt/admin/reports/inprogressRetrieves a list of all order reports that are in progress, by accountName. Be aware that the scope of the export log is per user. > This endpoint is for VTEX…

User orders

  • GETRetrieve user's orders/api/oms/user/orders?clientEmail=customer@mail.com&page=15&per_page=15Lists all orders from a given client, filtering by their email. > Note that these requests are meant to be made by Call center operator profiles. Otherwise,…
  • GETRetrieve user order details/api/oms/user/orders/:orderId?clientEmail=customer@mail.comLists all details from a user's order, through client's perspective. > Note that these requests are meant to be made by Call center operator profiles.…

Change seller

  • GETGet window to change seller/api/checkout/pvt/configuration/window-to-change-sellerRetrieves a marketplace’s window to change seller, that is, the period when it is possible to choose another seller to fulfill a given order after the…
  • POSTUpdate window to change seller/api/checkout/pvt/configuration/window-to-change-sellerUpdates a marketplace’s window to change seller, that is, the period when it is possible to choose another seller to fulfill a given order after the original…

Feed v2 (deprecated)

  • GETGet feed order status/api/oms/pvt/feed/orders/status?maxLot={{maxLot}}Get feed order status (deprecated)

API details

Base URL
https://vtex.local
https://{accountName}.{environment}.com.br
Authentication
An API key in the X-VTEX-API-AppKey header
An API key in the X-VTEX-API-AppToken header
Operations
28 operations on 22 pathsGET 13POST 11DELETE 2PUT 1PATCH 1
Main resources
Feed v3 6Orders 6Order hook 3Change seller 2Export order report 2Invoice 2Payment 2User orders 2Conversation 1Feed v2 (deprecated) 1
Response formats
application/json application/json; charset=utf-8 text/plain
Description format
OpenAPI 3.0.0, API version 1.0
Listed from
APIs.guru OpenAPI Directory (CC0-1.0)
Source updated

How to test the Orders API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Orders API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses an API key in the X-VTEX-API-AppKey header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “List orders” (GET /api/oms/pvt/orders?orderBy=v502556llux-01,asc&page=10&per_page=15&f_creationDate=creationDate:[2016-01-01T02:00:00.000Z TO 2021-01-01T01:59:59.999Z]&f_hasInputInvoice=false&q=- OrderID: v212333lux-02 - Client email: taylor@email.com - Client document: 21133355524 - Client name: Taylor&utc=-2000&f_shippingEstimate=0.days&f_invoicedDate=invoicedDate:[2022-01-01T02:00:00.000Z TO 2022-01-02T01:59:59.999Z]&f_authorizedDate=creationDate:[2022-01-01T02:00:00.000Z TO 2022-01-02T01:59:59.999Z]&f_UtmSource=christmas_campaign&f_sellerNames=SellerName&f_callCenterOperatorName=Operator%20Name&f_salesChannel=Main&salesChannelId=1&f_affiliateId=WLM&f_status=ready-for-handling&incompleteOrders=true&f_paymentNames=Visa&f_RnB=Free+Shipping&searchField= - SKU ID: `25` - Gift List ID: `11223` - Transaction ID (TID): `54546300238810034995829230012` - PCI Connector's Transaction ID (TID): `7032909234899834298423209` - Payment ID (PID): `2` - Connector's NSU: `2437281`&f_isInstore=true), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Orders API?

>Check the new [Orders onboarding guide](https://developers.vtex.com/docs/guides/orders-overview). We created this guide to improve the onboarding experience… It is listed under Other and has 28 endpoints.

Who publishes the Orders API?

It is listed from VTEX's public API description (an OpenAPI document), not published by VTEX on Swastik Codes. Anyone who controls vtex.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Orders API?

Its description lists 2 base URLs: https://vtex.local, https://{accountName}.{environment}.com.br. The first is the usual one; the others are typically sandbox or regional servers.

How do I authenticate with the Orders API?

It accepts 2 methods: an API key in the X-VTEX-API-AppKey header; an API key in the X-VTEX-API-AppToken header.

How many endpoints does the Orders API have?

28 operations on 22 paths (13 GET, 11 POST, 2 DELETE, 1 PUT, 1 PATCH). The largest groups are Feed v3, Orders, Order hook, Change seller.

Is forking the Orders API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.