The VTEX Tracking app automatically gets invoiced orders’ information from VTEX’s Order Management System (OMS) so as to create delivery routes. However, it is possible to import external orders by using our APIs.

Since the actual fulfillment and tracking only happens for invoiced orders, external order integrations must accomplish four steps in order to create and move the imported orders along the OMS’s workflow to the invoiced status. The steps are:

1. Place order
2. Authorize dispatch
3. Start handling
4. Send invoice

Because this type of integration assumes payment is already taken care of when orders are imported, we can use the fulfillment order workflow. This is the same workflow used by sellers integrating with marketplaces, for example.

Make sure you have API authentication credentials in order to use the APIs listed below.

This step actually creates the order in the OMS.

To do this, use the Place fulfillment order API request.

In order to successfully place an order on the platform, you must have products already registered in your VTEX catalog and make sure they are available in the platform's inventory. For this purpose, it may be a good idea to set infinite inventory.

The field marketplaceServicesEndpoint is required, but not necessarily applicable in the context of integrating orders to VTEX Tracking. Because of this, you may send it with a mock value not corresponding with a real working endpoint, such as https://exampleseller.marketplaceservices.com.

Because we are using endpoints typically used by sellers connecting to external marketplaces, steps 1 and 2 will require you to send the affiliateId field.

This field is meant to be a three-letter code identifying the marketplace that made the sale to be fulfilled. In the case of importing external orders to VTEX Tracking, you may send any arbitrary three-letter code and the requests should work as expected.

For a given order you should use the same affiliateId, orderId and marketplaceOrderId in steps 2, 3 and 4, as used in this first step when required in the API requests. The orderId will be in the response of the Place fulfillment order request and it is composed of the affiliateId and marketplaceOrderId joined by a “-. Do not use an affiliate that is configured to use the seller's payment methods, or else this request will return a status 500. In this case, create a new affiliate without this configuration or use an arbitrary affiliateId`.

To move the created order to the next status, use the Authorize dispatch for fulfillment orders request.

After dispatch is authorized, the order goes automatically into the grace period also known as the cancellation window. This is a period of time in which the store waits to see if the customer wants to cancel the purchase before it actually starts handling the order. This window is set to 30 minutes by default, but can be changed in the Order Management settings. Learn how to set the grace period for order cancelation.

After the grace period, the order status will be ready-for-handling. To move it to the next status, use the Start handling order API request.

Use the Order invoice notification request to send invoice information to VTEX.

Note that this step can occur in parallel to steps 2 and 3. Once an order has been created, the platform can receive its invoice information.

You can use the Order invoice notification request to send all invoice information at once, or you can send part of the information and update the invoice with the rest of the information later by using the Update order's partial invoice request.

An example of the latter is when you need to include a tracking number to an invoice that is already registered to the platform.

This request can be used to send the link to the XML of the invoice, which can be relevant to some VTEX Tracking integrations. Find if that is your case and learn more in this article on how to install and configure the VTEX Tracking app.

During integration or after you are done integrating a given order with these steps, you can check the order's information and progress in the Order Management section in VTEX Admin or with the Orders API.

For order information related to VTEX Tracking, see the VTEX Tracking API documentation.