API Integration

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

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

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:

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

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

{
   "items":[
      {
         "id":"8",
         "quantity":1,
         "seller":"1",
         "price":12
      },
 {
"marketplaceOrderGroup": "847392476",
"authorizationReceipt":  {
        "date": "{date}",
        "receipt": "{receipt}"
    }
}
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 ordergroup
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

{ 
"id":"sellerOrderCancelled", 
"sellerOrderId": "7908010136043"
}
Name Type Mandatory Description
orderGroup string Yes Path parameter including the marketplace order ID or ordergroup.
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:

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

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