Fulfillment simulation

This endpoint may be called upon by VTEX for fulfillment simulation in the external seller different contexts. See examples below.

When a Notification request returns a response with status 200 OK, it means that the SKU already exists in the marketplace. Whenever this happens, the marketplace will call the seller to get two updated information about the SKU: Price and Inventory.

The seller needs to have an endpoint implemented in order to receive this call and send a response containing the requested information to the marketplace. We call it the Fulfillment Simulation endpoint.

If the seller wishes to include other parameters in this call (like account name, or sales channel ID), this should be done within their {fulfillmentEndpoint}. This path is then inserted in the marketplace's VTEX admin when configuring a seller.

The marketplace will send an object containing an array of items. The seller must use this list to get the updated information about the referred SKUs and send them back to the marketplace, following the response format explained in the API Reference.

This call is also applied in the Storefront simulation scenario, in which case the request from VTEX does not send the paramenters country and postalCode.

The call's response should be adapted to the requested context. For example, if the Fulfillment Simulation endpoint is called to display items in the storefront, the Address information can be nulled in the request (like country, or postalCode), since they are unnecessary data for this context. However, they become mandatory fields for shopping cart simulation, since address information is needed to calculate freight values.

Request body example - Indexing simulation

{
  "items": [
    {
      "id": "7908010136043",
      "quantity": 1,
      "seller": "1",
    }
  ],
  "isCheckedIn": false,
}

Request body example - Checkout simulation

{
  "items": [
    {
      "id": "7908010136043",
      "quantity": 1,
      "seller": "1",
    }
  ],
  "postalCode": "22270-030",
  "country": "BRA",
}

Response body fields to be sent by the seller

Name Type Mandatory Description
country string Yes ISO 3-digit code of the country where the delivery address is located. If you don’t want to send it, use the value null.
items array Yes Contains the data about each SKU in the cart.
↳ requestIndex integer Yes Posição desse item no array original (request)
↳ attachmentOfferings array No Contains the attachments that are available for the SKU customization. If this array is sent, the following fields are mandatory. If you don’t have any attachment to send, this array should be empty.
 ↳ name string Yes Attachment name.
 ↳ required boolean Sets the attachment as mandatory (value = true) or not (value = false).
 ↳ schema object Yes Schema for customization.
  ↳ maximumNumberOfCharacters integer Yes Maximum number of characters for the attachment.
↳ id string Yes SKU ID.
↳ listPrice integer Yes List price. It’s the amount presented to the customer as a “previous” price that has been lowered due to a discount. Don’t separate the decimal places. The last two digits are the cents.
↳ measurementUnit string No SKU’s measurement unit.
↳ merchantName string No Name of the marketplace, used to guide payments. This field should be nulled if the marketplace is responsible for processing payments. Check out our [Split Payment](https://help.vtex.com/en/tutorial/split-de-pagamento--6k5JidhYRUxileNolY2VLx) article to know more.
↳ offerings array No Services that may be offered for this SKU. Examples are the assembly of a piece of furniture or warranty. In case these information are sent, the following fields are mandatory. If you don’t want to send it, use an empty array.
 ↳ type string Yes Type of the service.
 ↳ id string No Service ID.
 ↳ name string Yes Service name.
 ↳ price integer Yes Service price. The last two digits are the cents.
↳ price integer Yes Actual selling price of the SKU. Don’t separate the decimal places. The last two digits are the cents.
↳ priceTags array No List with the promotions applied to the SKU.
↳ priceValidUntil string No Expiration date of the SKU price. Example: "2014-03-01T22:58:28.143". In case you don’t want to send it, use the value null.
↳ quantity integer Yes Quantity of the item. The seller should send the quantity that was indicated in the request, or the maximum quantity possible.
↳ seller integer Yes ID of the seller as registered in VTEX. You should send the same value that came in the request.
↳ unitMultiplier integer No SKU unit multiplier. The default value is 1.
logisticsInfo array Yes Array that contains the data regarding the delivery methods and stock for each item. If all products are unavailable, this field should return empty.
↳ itemIndex integer Yes Position of this item in the original array, i.e., in the array that came with the request. This index is what identifies which SKU you are referring to for each object inside the logisticsInfo.
↳ quantity integer Yes Quantity of the item. The seller should send the quantity that was indicated in the request, or the maximum quantity possible.
↳ shipsTo array Yes ISO 3-digit code of the countries to where the SKU is delivered.
↳ slas array Yes Contains the available delivery methods.
 ↳ id integer Yes Identifier of the delivery method.
 ↳ deliveryChannel string Yes Type of sales channel. The values that are possible are: pickup-in-point for pickup point and delivery for regular delivery.
 ↳ name string Yes Name of the delivery method.
 ↳ shippingEstimate string Yes Time estimated for the delivery. Possible suffixes are bd for “business day” , h for “hours”, and m for “minutes”.
 ↳ price integer Yes Delivery price. The two last digits are the cents.
 ↳ availableDeliveryWindows array No Contains the delivery windows available for the SLA. Below fields with * are required if delivery windows are sent.
  ↳ startDateUtc string Yes Start date of the delivery window.
  ↳ endDateUtc string Yes End date of the delivery window.
  ↳ price integer Yes Extra price for scheduled delivery. The last two digits are the cents.
 ↳ pickupStoreInfo object Yes Contains the data about the pickup point. If you don’t want to send this, use the value null.
  ↳ isPickupStore boolean Yes true if it is a pickup point.
  ↳ friendlyName string Yes Friendly name of the pickup point.
  ↳ address array Yes Address data of the pickup point.
   ↳ addressType string Yes The possible value is pickup.
   ↳ receiverName array No Name of the person who will receive the product. May be sent as null.
   ↳ addressId string Yes Identifies the pickup point.
   ↳ postalCode string Yes Postal code of the pickup point. This field is mandatory, for shopping carts simulations, where both Country and Postal Code are required. This field should be sent as `null` for storefront simulations, where the information is not necessary.
   ↳ city string Yes City of the pickup point.
   ↳ state string Yes State of the pickup point.
   ↳ country string Yes 3-digit ISO code of the country where the pickup point is located.
   ↳ street string Yes Street where the pickup point is located.
   ↳ number string Yes Address number of the pickup point.
   ↳ neighborhood string Yes Neighborhood where the pickup point is located.
   ↳ complement string No Complement of the pickup point address.
   ↳ reference string No A reference for the pickup point address.
   ↳ geoCoordinates array Yes Contains the geographic coordinates of the pickup point.
  ↳ additionalInfo string No Description or extra information about the pickup point.
↳ stockBalance integer Yes Stock balance of the SKU.
↳ deliveryChannels array Yes Contains the stock balance for each channel.
 ↳ id string Yes Identifies the channel type whose stock balance will be informed in the next field. Possible values are: pickup-in-point for pickup point and delivery for regular delivery.
 ↳ stockBalance integer Yes Stock balance for the channel type selected in the previous field.
geoCoordinates array No Geographic coordinates of the delivery address. If it’s not sent, use an empty array here.
postalCode string No Postal code of the delivery address. This field is mandatory, for shopping carts simulations, where both Country and Postal Code are required. This field should be sent as `null` for storefront simulations, where the information is not necessary.

Response body example

{
   "country": "BRA",
   "items": [
         {
         "id": "2000037",
         "listPrice": 67203,
         "measurementUnit": "un",
         "merchantName": "mySeller1",
         "offerings":[
           {
              "type": "Warranty",
              "id": "5",
              "name": "1 year warranty",
              "price": 10000
           }
        ],
         "price": 67203,
         "priceTags": [],
         "priceValidUntil": null,
         "quantity": 1,
         "requestIndex": 0,
         "seller": "1",
         "unitMultiplier": 1
      }
   ],
   "logisticsInfo": [
      {
         "itemIndex": 0,
         "quantity": 1,
         "shipsTo": [
            "BRA"
         ],
         "slas": [
            {
               "id": "Regular",
               "deliveryChannel": "delivery",
               "name": "Regular Delivery",
               "price": 846,
               "shippingEstimate": "19bd"
            },
            {
               "id": "Curbside pickup",
               "deliveryChannel": "pickup-in-point",
               "name": "Curbside pickup",
               "shippingEstimate": "0bd",
               "price": 0,
               "availableDeliveryWindows": [
                {
                   "startDateUtc": "2013-02-04T08:00:00+00:00",
                   "endDateUtc": "2013-02-04T13:00:00+00:00",
                   "price": 0
                }
              ],
               "pickupStoreInfo": {
                  "isPickupStore": true,
                  "friendlyName": "Santa Felicidade",
                  "address": {
                     "addressType": "pickup",
                     "receiverName": null,
                     "addressId": "548304ed-dd40-4416-b12b-4b32bfa7b1e0",
                     "postalCode": "82320-040",
                     "city": "Curitiba",
                     "state": "PR",
                     "country": "BRA",
                     "street": "Rua Domingos Strapasson",
                     "number": "100",
                     "neighborhood": "Santa Felicidade",
                     "complement": "Loja 10",
                     "reference": null,
                     "geoCoordinates": [
                        -49.334934,
                        -25.401705
                     ]
                  },
                  "additionalInfo": ""
               }
            }
         ],
         "stockBalance": 199,
         "deliveryChannels": [
            {
               "id": "delivery",
               "stockBalance": 179
            },
            {
               "id": "pickup-in-point",
               "stockBalance": 20
            }
         ]
      }
   ],
   "postalCode": "80250000"
}
Language
Authentication
Click Try It! to start a request and see the response here!