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"
}