Fulfillment simulation - External Seller

post https://{fulfillmentEndpoint}/pvt/orderForms/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 payload can be adapted into two scenarios:

Displaying items in the storefront: the address information can be nulled in the request, since they are not mandatory data for this context.
Making a shopping cart simulation during checkout: address information must be sent, since this data is needed to calculate freight values. If the address information (including postalCode and country) is not sent through the call, VTEX interprets the stock balance as zero. Without a valid stock balance, the seller will not be shown as an option during checkout.

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!