Multilevel omnichannel inventory API integration

Logistics

Marketplaces following the External Marketplace protocol can also make the Multilevel Omnichannel Inventory setting available for VTEX sellers connected to it. This allows for more fulfillment options by VTEX sellers, since they can connect their franchise accounts' inventories as fulfillment options. You can learn more about the benefits and restrictions of implementing this feature in our Multilevel Omnichannel Inventory Help article.

External marketplaces and connectors should follow this article's instructions to configure Multilevel Omnichannel Inventory in their marketplace architecture with VTEX.

Before you begin, make sure that the necessary settings are made in the connected VTEX account, so the feature is fully operational.

API integration overview

When using a Multilevel Omnichannel Inventory architecture, the endpoints used in the integration's architecture are the following:

Place Order: create the order in the seller responsible for fulfillment.
Marketplace Order Authorization: progressing the order, after the marketplace's authorization.
Cancel Order Notification: route to be notified of the seller's, or of the chain agent's (in this case seller level 2) cancellation.
Order Invoice Notification: route to receive invoice notification from the seller, or of the chain agent's (in this case seller level 2).

Therefore, the flow of the routes follows the image below:

{"base64":" ","img":{"width":1758,"height":832,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":190028,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/multilevel-omnichannel-inventory-1.png"}}

Place Multilevel Omnichannel Order

Use the request example below to Place Order.

Method: PUT
URL: {host}/api/checkout/pvt/orders?sc={sc}&affiliateId={affiliateId}

Request example:


_44{
_44   "items":[
_44      {
_44         "id":"8",
_44         "quantity":1,
_44         "seller":"1",
_44         "price":12
_44      },
_44      {
_44         "id":"36",
_44         "quantity":1,
_44         "seller":"1",
_44         "price":120
_44      }
_44   ],
_44   "clientProfileData":{
_44      "email":"sicrano@mailinator.com"
_44   },
_44   "shippingData":{
_44      "attachmentId":"shippingData",
_44      "logisticsInfo":[
_44         {
_44            "itemIndex":0,
_44            "selectedSla":"Retirada (14b25e5)",
_44            "selectedDeliveryChannel":"pickup-in-point",
_44            "price":0
_44         },
_44         {
_44            "itemIndex":1,
_44            "selectedSla":"Normal",
_44            "selectedDeliveryChannel":"delivery",
_44            "price":0
_44         }
_44      ],
_44      "selectedAddresses":[
_44         {
_44            "addressId":"-4581767308704"
_44         }
_44      ]
_44   },
_44   "marketplacePaymentValue":1550,
_44   "marketplaceOrderGroup":"externalMarketplace10",
_44  "marketplaceServicesEndpoint":"http://service.externalmarketplace.com/api/orders?parameter=value"
_44}

Changes in the order's data

The Multilevel Omnichannel Inventory changes and adds fields to the order's data. You can know more about the fields in the Retrieve user order details API Reference.

The table below describes the fields that were added or changed in the order's data.

Field	New or Changed?	Description
sc	New	Path parameter including the sales channel ID.
marketplaceServicesEndpoint	New	Field is added to the orderform. This field should be filled in with the information provided by the external marketplace that is placing an order in VTEX.
marketplaceOrdergroup	New	Field is added to the orderform. This field should be filled in with the information provided by the external marketplace that is placing an order in VTEX.
affiliateId	New	The afiliate identification code created by the seller. The seller must inform this ID to the marketplace so that the marketplace can complete the configuration process.
marketplacePaymentValue	New	Field is added to the orderform.
transaction	Changed	This field no longer is required in the orderform.
origin	Changed	The field 'origin' will come with `chain` as a value, and not `fulfillment` or `marketplace` like before.
paymentData	Changed	The field is no longer required in chained orders.

Marketplace Order Authorization

The marketplace must implement the following endpoint to notify the chain order that its progress has been approved:

Method: POST
URL: {host}/api/checkout/pvt/orders/{orderId}/receipts/marketplace-order-authorization

Request example


_15{
_15   "items":[
_15      {
_15         "id":"8",
_15         "quantity":1,
_15         "seller":"1",
_15         "price":12
_15      },
_15   ],
_15   "marketplaceOrderGroup": "847392476",
_15   "authorizationReceipt":  {
_15        "date": "{date}",
_15        "receipt": "{receipt}"
_15    }
_15}

Name	Type	Mandatory	Description
orderId	String	Yes	Path parameter with the Chain order ID.
items	Array of objects	Yes	Array containing the SKUs that are being invoiced.
id	String	Yes	ID of the SKU being invoiced.
price	Integer	Yes	Total price of the SKU being invoiced in cents. Do not use any decimal separator. For instance, $24.99 should be represented as 2499.
seller	String	Yes	Account name of the seller responsible for fulfillment
quantity	Integer	Yes	Quantity currently in inventory of the SKU being invoiced.
marketplaceOrderGroup	String	Yes	Marketplace order ID or order group
authorizationReceipt	Object	Yes	Object including date and receipt of authorization
date	String	Yes	Date of authorization
receipt	String	Yes	Receipt number

Cancel Order Notification

The marketplace must implement the endpoint below, to receive the cancel notification from the VTEX seller.

Method: POST
URL: https://{baseUrldoParceiro}/pvt/orders/order-group/{orderGroup}/notifications/seller-cancellation

Request example


_10{ 
_10    "id":"sellerOrderCancelled", 
_10    "sellerOrderId": "7908010136043"
_10}

Name	Type	Mandatory	Description
orderGroup	String	Yes	Path parameter including the marketplace order ID or order group.
id	String	Yes	ID of the canceled order by the seller.
sellerOrderId	String	Yes	Order ID in the VTEX system.

Order Invoice Notification

The marketplace must implement this endpoint for the chain order to inform it about the order invoice. Check out our Order Invoice Notification to know more details.

Method: POST
URL: {marketplaceServiceEndpoint}/api/oms/pvt/orders/{orderId}/invoice

Note that the path including /pvt is usually called if the notification is meant for an internal VTEX endpoint. If calling external agents, substitute the path for /pub.

Request example:


_17{
_17 "invoiceNumber":"7999972",
_17 "invoiceValue":7450,
_17 "issuanceDate":"2019-02-07T02:00:00.000Z",
_17 "invoiceUrl":"http://www.invoiceu.rl",
_17 "invoiceKey":"799",
_17 "trackingNumber":"9997LUX",
_17 "trackingUrl":"http://www.trackingu.rl",
_17 "courier":"All postal codes",
_17 "items": [
_17      {
_17         "id": "1231",
_17         "price": 7450,
_17         "quantity": 1
_17      }
_17   ]
_17}

Name	Type	Mandatory	Description
invoiceNumber	String	Yes	Number that identifies the invoice.
invoiceValue	String	Yes	Total amount being invoiced in cents. Do not use any decimal separator. For instance, $24.99 should be represented as 2499.
issuanceDate	String	Yes	Issuance date of the invoice.
invoiceUrl	String		URL of the invoice. Can be used to send the URL of an XML file, for example, which is useful for some integrations.
trackingNumber	String	No	The number code that identifies the order tracking. This field should only be used when sending the tracking information. When the request is used for sending the invoice, this field should be left empty.
trackingUrl	String	No	The URL used to track the order. This field should only be used when sending the tracking information. When the request is used for sending the invoice, this field should be left empty.
courier	String	No	The name of the carrier responsible for delivering the order. This field should only be used when sending the tracking information. When the request is used for sending the invoice, this field should be left empty.
items	Array of objects	Yes	Array containing the SKUs that are being invoiced.
id	String	Yes	ID of the SKU being invoiced.
price	Integer	Yes	Total price of the SKU being invoiced in cents. Do not use any decimal separator. For instance, $24.99 should be represented as 2499.
quantity	Integer	Yes	Quantity currently in inventory of the SKU being invoiced.

Response example:


_10{
_10    "date": "2018-11-21T11:50:09.9994509-02:00",
_10    "orderId": "876053333998-01",
_10    "receipt": "95233cf2078d418ba77155380c18f398"
_10}

Next steps

Checkout the Change chain orders in external marketplaces article to learn how to implement more complex change order scenarios.