We have released a new method for integrating orders from external marketplaces, as a part of our Marketplace Protocol. If you used this previous method for integrating orders, you can still find their documentation in Order Logs and How to collect orders from sales channels. These previous methods, however, will not be maintained. If you are integrating orders for the first time, we recommend you use the instructions in our New Order Integration guide.

Orders in an integration fit into two different categories:

Paid orders: the marketplace only makes orders available for the integration once they are paid by the customer.

Orders to be paid: the marketplace makes orders that have not been paid by the customer available for the integration.

Right after the payment confirmation by the marketplace, the flow goes as the image below describes it:

A marketplace order can reach the connector by either a:

1. Notification sent by the marketplace: when the marketplace informs the connector about the existence of an order, and the connector, after receiving the notification, goes to the marketplace to get order details.

2. Polling request made by the connector: when the connector checks the marketplace from time to time, to collect new orders.
   

Follow the steps below, to integrate orders from external marketplaces:

1. Collect order details from the endpoint provided by the marketplace.

2. Create a request on the Place fulfillment order endpoint.

3. Simulate fulfillment, to check if the SKU is available in VTEX.

4. For each SKU retrieved, the connector must call the Get SKU and Context endpoint and:

   a. Validate if the SKU is active through the isActive property.

   b. Validate if the SKU is associated to the sales channel used in the integration through the salesChannel property.

5. In case step 4 retrieves all SKUs that compose the order with their respective inventory levels and prices, the connector should insert the order through the Order Placement endpoint.

• In the marketplaceServicesEndpoint field, the endpoint will be used by VTEX to inform the connector of the changes in order status, inserting tracking code and invoice. For more information check out Sending invoice and tracking code to the marketplace.

6. In case step 5 returns success and creates the order within the VTEX platform, authorize the dispatch by the seller through the Authorize dispatch for fulfillment order endpoint.
7. Check the Recommendations page to follow integration best practices.
8. Check out the Order logs page to create appropriate error messages.

If all validations pass, the order is sent to VTEX and the operation is logged according to information described in the Order logs.

After VTEX OMS returns success, if the IDs between VTEX and the marketplace differ, the connector should store the mapping of the order (VTEX ID and Marketplace ID). This information will be used for order status update operations.

Be mindful to make all validations at once. In case there's an error detected, the connector presents the seller a list of actions to correct. This way we can avoid the correct - publish - correct cycle. If orders do not apply to the steps above, an error log must be filed.

Use the endpoints described below to perform this step. It is important to note that when consuming this API, the connector must have a valid VTEX App Key and App Token. The diagram illustrates the endpoints used in the integration:

All parameters in the endpoints below must be declared in the request. In case one of the parameters does not have a value, you must still send it as null.

Use the curl example below to perform the fulfillment Simulation.

Use the request example below to perform the Shopping Cart Simulation. Check out our Shopping cart Simulation API Reference to know more details.

Use the request example below to place fulfillment order. Check out our Place fulfillment order API Reference to know more details.

Use the request example below to authorize dispatch. Check out our Authorize Dispatch API Reference to know more details.

When to perform: after attempting to integrate an order in VTEX platform, the process returns an error FMT007 - signaling price divergence.

Connectors should:

1. In case the call is successful (200 OK), signaling the creation of prive divergence rule, the order should be queued in VTEX.
2. In case the call returns a bad request (400), signaling that the order could not be inserted for infringing price divergence rules, file an error log, following the error code x.
3. In case the call returns an unauthorized request (500), signaling that the price divergence rule failed due to error in system communication, the order should be queued on the connector’s flow to perform a retry.

When to perform: after attempting to integrate an order in VTEX platform, the process returns an error ORDER027 - signaling inventory error.

Connectors should:

1. Generate an error log, according to the item x.
2. Validate if the order status in the marketplace was altered to canceled. If so, generate the error log message x, and remove the order from the retry queue.
3. If the order was not canceled, submit the order to be reprocessed.
4. In case the call is successful (200 OK), signaling the creation of the order, connectors should log the operation according to x.
5. In case the call returns a bad request (400), signaling that the order could not be inserted for infringing stock rules, file an error log, following the error code x.
6. In case the call returns an server error (500), signaling that the order creation failed due to error in system communication, the order should be queued on the connector’s flow to perform a retry.

When to perform: after attempting to integrate an order in VTEX platform, the process returns an error ORDER027 - signaling that there are no carriers to attend that order.

Connectors should:

1. Generate an error log, according to the item x.
2. Validate if the order status in the marketplace was altered to canceled. If so, generate the error log message x, and remove the order from the retry queue.
3. If the order was not canceled, submit the order to be reprocessed.
4. In case the call is successful (200 OK), signaling the creation of the order, connectors should log the operation according to x.
5. In case the call returns a bad request (400), signaling that the order could not be inserted for infringing carriers’ rules, file an error log, following the error code x.
6. In case the call returns a server error (500), signaling that the order creation failed due to error in system communication, the order should be queued on the connector’s flow to perform a retry.

When to perform: after attempting to integrate an order in VTEX platform, the process returns an error ORDER027 - signaling that there are no pickup points for the end customer to retrieve their order.

Connectors should:

1. Generate an error log, according to the item x.
2. Validate if the order status in the marketplace was altered to canceled. If so, generate the error log message x, and remove the order from the retry queue.
3. If the order was not canceled, submit the order to be reprocessed.
4. In case the call is successful (200 OK), signaling the creation of the order, connectors should log the operation according to x.
5. In case the call returns a bad request (400), signaling that the order could not be inserted for infringing pickup points’ rules, file an error log, following the error code x.
6. In case the call returns an unauthorized request (500), signaling that the order creation failed due to error in system communication, the order should be queued on the connector’s flow to perform a retry.

When to perform: when the order is canceled by the marketplace.

Connectors should:

1. Verify if the order exists in the VTEX platform, by either: a. Checking the order ID relation between VTEX and the marketplace in their environment. b. Checking if the order exists through the Get Order endpoint.

2. Validate the order status.

3. If the order exists in VTEX, call the Cancel Order endpoint.

4. If the order exists in VTEX, and the order status is invoiced, call the Order Invoice notification endpoint.

5. In case the call is successful (200 OK), signaling the cancelling of the order, connectors should log the operation according to x.

6. In case the call returns a bad request (400), signaling that the order could not be canceled, file an error log, following the error code x.

7. In case the call returns an unauthorized request (500), signaling that the order cancelling failed due to error in system communication, the order should be queued on the connector’s flow to perform a retry.

Make sure that all steps are logged as either success or failure, to offer the operation’s full traceability. Check out the Order logs page to learn more.