If you used our previous method for integrating orders, you can still find their documentation in Order Logs and How to collect orders from sales channels. The previous method, however, will not be maintained. If you are integrating orders for the first time, we recommend you use the instructions in this article.
Authentication/authorization
When sending a request to our APIs, you must inform in the headers a X-VTEX-API-AppKey + X-VTEX-API-AppToken pair or a VtexIdclientAutCookie (the connector’s app token, if using our App Template) that has access to the specified account.
API Reference: New order Integration
Use the request example below to Place an order. The description and requirement of each of the fields present in the request body are found in our API Reference.
It’s important to note that although some fields are optional in our API, depending on the order's country of origin or trade policy, they may be mandatory for Checkout/Fulfillment. In such cases, when trying to process the order, we will return the validation error in question to the connector, as well as other possible errors and success notifications.
_98{_98 "marketplaceOrderId": string,_98 "connectorName": string,_98 "connectorEndpoint": string,_98 "marketplaceOrderStatus": string,_98 "marketplacePaymentValue": int,_98 "marketplaceInterestValue": int,_98 "priceDivergenceAllowanceRate": decimal,_98 "allowFranchises": bool,_98 "pickupAccountName": string,_98 "items": [_98 {_98 "id": string,_98 "price": int,_98 "quantity": int_98 }_98 ],_98 "clientProfileData": {_98 "email": string,_98 "firstName": string,_98 "lastName": string,_98 "phone": string,_98 "document": string,_98 "corporateDocument": string,_98 "corporatePhone": string,_98 "corporateName": string,_98 "tradeName": string,_98 "stateInscription": string_98 },_98 "shippingData": {_98 "logisticsInfo": [_98 {_98 "price": int,_98 "selectedDeliveryChannel": string,_98 "selectedSla": string,_98 "lockTTL": string,_98 "shippingEstimate": string,_98 "deliveryIds": [_98 {_98 "warehouseId": string_98 }_98 ]_98 }_98 ],_98 "selectedAddresses": [_98 {_98 "addressType": string,_98 "addressId": string,_98 "receiverName": string,_98 "postalCode": string,_98 "city": string,_98 "state": string,_98 "country": string,_98 "street": string,_98 "number": string,_98 "neighborhood": string,_98 "complement": string,_98 "geoCoordinates": {_98 "latitude": double,_98 "longitude": double_98 }_98 }_98 ],_98 "isFob": bool,_98 "isMarketplaceFulfillment": bool,_98 "trackingHints": [_98 {_98 "trackingId": string,_98 "courierName": string,_98 "trackingUrl": string,_98 "trackingLabel": string_98 }_98 ]_98 },_98 "invoiceData": {_98 "userPaymentInfo": {_98 "paymentMethods": string[]_98 }_98 },_98 "customData": {_98 "customApps": [_98 {_98 "id": string,_98 "major": int,_98 "fields": {_98 string: string_98 }_98 }_98 ]_98 },_98 "taxData": [_98 {_98 "skuId": string,_98 "value": int_98 } _98 ],_98 "openTextField": string_98}
Response Notifications
To receive notifications from our service, the connector must implement some API routes in the base endpoint informed in connectorEndpoint (be in the request or the App Template). Order Processing Result
Notifications with the orders processing result are sent through the following request: POST {connectorEndpoint}/order-integration/notification/processing-result?an={accountName}. The body is the same as described here.
Response Body
All API responses and order notifications from our service return the same data contract, as detailed bellow:
_21{_21 "accountName": string,_21 "success": bool,_21 "flow": string,_21 "operationId": string,_21 "marketplaceOrderId": string,_21 "code": string,_21 "message": string,_21 "errors": _21 [_21 {_21 "source": string,_21 "code": string,_21 "description": string_21 }_21 ],_21 "fields": {_21 "mainOrderId": string,_21 "franchiseOrderId": string_21 }_21}
Some fields can return as null in some cases, such as accountName, marketplaceOrderId and operationId, for example.
Response Codes
Code | Description |
---|---|
SOI001 | The order was integrated into VTEX successfully |
SOI002 | The order was approved in VTEX successfully |
SOI003 | The order was successfully enqueued in our service for processing |
EOI000 | An unknown error occurred when processing the order, and in this case, the solution would be contacting VTEX for support |
EOI001 | An unmapped error occurred when processing the order, and more details about the error can be found in the response error list |
EOI002 | There are no SLAs or items available to fulfill this order. That is: the item(s) can be without stock, inactive in the catalog or not included in connector’s trade policy; the SLA/pickup point chosen in the order is not available or doesn’t have stock for the order’s items; or there aren’t any SLAs available at all to fulfill the order |
EOI003 | The order total payment value differs from what is expected by the seller, and they do not have Order Authorization rules set up to deal with price divergence |
EOI004 | This order's cart is invalid. That can mean that either the item(s) in it don’t exist in VTEX catalog or the order's data doesn’t comply with the store configuration (for example, the minimum total value or quantity of items set by the seller was not reached in the order) |
EOI005 | A validation error occurred while trying to process the order. That is, some field/value sent in the order’s contract is invalid and not filled according to our’s or Checkout/Fulfillment’s documentation |
EOI006 | An unexpected error occurred in one of VTEX's internal services. Please try to send the request again later, as it’s possible one of our services is going through instabilities |
EOI007 | The order specified already exists in VTEX and we are not able to create duplicated orders |
EOI008 | The order cannot be approved because it’s not integrated in VTEX yet |
EOI009 | This order is out of the valid status to approve, such as canceled, for example |
EOI010 | The request to our API timed out, meaning we exceeded the response time limit |
EOI011 | The order was integrated with a price divergence, and we cannot approve it yet because we are waiting for the seller's manual authorization before proceeding |
Order Notification Results
- Error
- EOI000 - Unknown error
- EOI001 - Unmapped error
- EOI002 - SLA not available
- EOI003 - Price divergence
- EOI004 - Invalid cart
- EOI005 - Validation error
- EOI006 - VTEX unexpected error
- EOI007 - Duplicated order
- Success
- SOI001 - Order integrated
Scenario 1: new order, with pending payment
To integrate orders with pending payment, you just need to set the marketplaceOrderStatus field to NEW in the New Order Integration request.
Response
_11{_11 "marketplaceOrderId": null,_11 "accountName": "connections",_11 "code": "SOI003",_11 "flow": "PlaceOrder",_11 "success": true,_11 "operationId": null,_11 "errors": null,_11 "fields": null,_11 "message": "Order successfully enqueued"_11}
Notification
_14{_14 "marketplaceOrderId": "123456789",_14 "accountName": "connections",_14 "code": "SOI001",_14 "flow": "PlaceOrder",_14 "success": true,_14 "operationId": "a1a0e124-6cfc-404e-a8c5-95f5a494dc86",_14 "errors": null,_14 "fields": {_14 "mainOrderId": "MKP-123456789",_14 "franchiseOrderId": null_14 },_14 "message": "Order integrated successfully"_14}
Scenario 2: Approved order, with approved payment
To integrate orders with approved payment (automatically approving them afterwards) you just need to set the marketplaceOrderStatus
field to approved
in the New Order Integration API request.
Response
_11{_11 "marketplaceOrderId": null,_11 "accountName": "connections",_11 "code": "SOI003",_11 "flow": "PlaceOrder",_11 "success": true,_11 "operationId": null,_11 "errors": null,_11 "fields": null,_11 "message": "Order successfully enqueued"_11}
Notification
Integration:
_14{_14 "marketplaceOrderId": "123456789",_14 "accountName": "connections",_14 "code": "SOI001",_14 "flow": "PlaceOrder",_14 "success": true,_14 "operationId": "8cd93fe7-db90-4e1b-b55f-890a61e72bad",_14 "errors": null,_14 "fields": {_14 "mainOrderId": "MKP-123456789",_14 "franchiseOrderId": null_14 },_14 "message": "Order integrated successfully"_14}
Approval:
_14{_14 "marketplaceOrderId": "123456789",_14 "accountName": "connections",_14 "code": "SOI002",_14 "flow": "ApproveOrder",_14 "success": true,_14 "operationId": "8cd93fe7-db90-4e1b-b55f-890a61e72bad",_14 "errors": null,_14 "fields": {_14 "mainOrderId": "MKP-123456789",_14 "franchiseOrderId": null_14 },_14 "message": "Order approved successfully"_14}
Scenario 3: order with interest
To integrate orders with additional interest values, you need to fill in the marketplaceInterestValue field, with the desired amount in the New Order Integration API request.
Response
_11{_11 "marketplaceOrderId": null,_11 "accountName": "connections",_11 "code": "SOI003",_11 "flow": "PlaceOrder",_11 "success": true,_11 "operationId": null,_11 "errors": null,_11 "fields": null,_11 "message": "Order successfully enqueued"_11}
Notification
_14{_14 "marketplaceOrderId": "123456789",_14 "accountName": "connections",_14 "code": "SOI001",_14 "flow": "PlaceOrder",_14 "success": true,_14 "operationId": "7425f2ef-0849-4b73-94c7-355982119e51",_14 "errors": null,_14 "fields": {_14 "mainOrderId": "MKP-123456789",_14 "franchiseOrderId": null_14 },_14 "message": "Order integrated successfully"_14}
Scenario 4: Order with discounts
To integrate orders with discounts, you need to apply the discount directly in the order in theNew Order Integration API request, before sending it to our service. This means:
- If shipping costs $10 for a SKU, but the marketplace is offering a 10% discount on it, the
price
inlogisticsInfo
should be $9 (in integer format, 900). - If the SKU is priced at $100, and the marketplace is offering a 10% discount on it, the
price
of the SKU initems
should be $90 (in integer format, 9000). - And when the marketplace is offering a discount applied to all shipping or all SKUs in the order, this value should be split between the items, for example:
- SKU 1 price: $10, SKU 2 price: $40. Marketplace discount: $10. SKU 1 final
price
initems
should be $5 (in integer format, 500) and SKU 2 finalprice
should be $35 (in integer format, 3500).
- SKU 1 price: $10, SKU 2 price: $40. Marketplace discount: $10. SKU 1 final
Response
_11{_11 "marketplaceOrderId": null,_11 "accountName": "connections",_11 "code": "SOI003",_11 "flow": "PlaceOrder",_11 "success": true,_11 "operationId": null,_11 "errors": null,_11 "fields": null,_11 "message": "Order successfully enqueued"_11}
Notification
_14{_14 "marketplaceOrderId": "123456789",_14 "accountName": "connections",_14 "code": "SOI001",_14 "flow": "PlaceOrder",_14 "success": true,_14 "operationId": "9e396ae7-1e76-4915-b1ba-adb860e177bd",_14 "errors": null,_14 "fields": {_14 "mainOrderId": "MKP-123456789",_14 "franchiseOrderId": null_14 },_14 "message": "Order integrated successfully"_14}
Scenario 5: Order delivered by the seller
To input an order delivered by the seller, you must do the following in theNew Order Integration API request:
- Fill the
selectedDeliveryChannel
field with the valuedelivery
. - Fill the
selectedSla
field with the name of the seller’s SLA selected to deliver this order. In this case, this field can also be left empty, and Fulfillment’s service will choose an available SLA automatically, if there’s any.
Response
_11{_11 "marketplaceOrderId": null,_11 "accountName": "connections",_11 "code": "SOI003",_11 "flow": "PlaceOrder",_11 "success": true,_11 "operationId": null,_11 "errors": null,_11 "fields": null,_11 "message": "Order successfully enqueued"_11}
Notification
_14{_14 "marketplaceOrderId": "123456789",_14 "accountName": "grocery1",_14 "code": "SOI001",_14 "flow": "PlaceOrder",_14 "success": true,_14 "operationId": "e30cf30c-7b89-4a04-aa20-eb3d116e2ac7",_14 "errors": null,_14 "fields": {_14 "mainOrderId": "MKP-123456789",_14 "franchiseOrderId": null_14 },_14 "message": "Order integrated successfully"_14}
Scenario 6: Order delivered by seller’s franchise (Multilevel Omnichannel Inventory)
To input an order delivered by a seller’s franchise, to allow the Multilevel Omnichannel Inventory feature, in the New Order Integration API request, you must do the following:
- Fill the
selectedDeliveryChannel
field with the valuedelivery
; - Fill the
selectedSla
field with the name of the seller’s SLA selected to deliver this order; - Set the
allowFranchises
field totrue
.
Response
_11{_11 "marketplaceOrderId": null,_11 "accountName": "connections",_11 "code": "SOI003",_11 "flow": "PlaceOrder",_11 "success": true,_11 "operationId": null,_11 "errors": null,_11 "fields": null,_11 "message": "Order successfully enqueued"_11}
Notification
_14{_14 "marketplaceOrderId": "123456789",_14 "accountName": "connections",_14 "code": "SOI001",_14 "flow": "PlaceOrder",_14 "success": true,_14 "operationId": "e1d447aa-c885-4b03-97c4-ddf20090a3c3",_14 "errors": null,_14 "fields": {_14 "mainOrderId": "MKP-123456789-01",_14 "franchiseOrderId": "MKT-MKP-123456789-01"_14 },_14 "message": "Order integrated successfully"_14}
Scenario 7: Order delivered by the marketplace (with stock in the seller)
To input an order delivered by the marketplace with the stock in the seller, in the New Order Integration API request, you must do the following:
- Fill the
selectedDeliveryChannel
field with the valuedelivery
. - Don’t fill the
selectedSla
field. - Set the
isFob
field totrue
. - Set the
isMarketplaceFulfillment
to false.
Response
_11{_11 "marketplaceOrderId": null,_11 "accountName": "connections",_11 "code": "SOI003",_11 "flow": "PlaceOrder",_11 "success": true,_11 "operationId": null,_11 "errors": null,_11 "fields": null,_11 "message": "Order successfully enqueued"_11}
Notification
_14{_14 "marketplaceOrderId": "123456789",_14 "accountName": "connections",_14 "code": "SOI001",_14 "flow": "PlaceOrder",_14 "success": true,_14 "operationId": "94c3242a-74b9-4261-9820-8e26bb73dbbd",_14 "errors": null,_14 "fields": {_14 "mainOrderId": "MKP-123456789",_14 "franchiseOrderId": null_14 },_14 "message": "Order integrated successfully"_14}
Scenario 8: Order delivered by the marketplace (with stock in the marketplace)
To input an order delivered by and with the stock in the marketplace, in the New Order Integration API request, you must do the following:
- Fill the
selectedDeliveryChannel
field with the valuedelivery
; - Don’t fill the
selectedSla
field; - Set the
isFob
field totrue
; - Set the
isMarketplaceFulfillment
totrue
; - Fill the
warehouseId
within thedeliveryIds
field with the id of the warehouse set by the seller to handle orders from the marketplace.
Response
_11{_11 "marketplaceOrderId": null,_11 "accountName": "connections",_11 "code": "SOI003",_11 "flow": "PlaceOrder",_11 "success": true,_11 "operationId": null,_11 "errors": null,_11 "fields": null,_11 "message": "Order successfully enqueued"_11}
Notification
_14{_14 "marketplaceOrderId": "123456789",_14 "accountName": "grocery1",_14 "code": "SOI001",_14 "flow": "PlaceOrder",_14 "success": true,_14 "operationId": "42ca5760-e229-49b1-a731-73bebd0c48a0",_14 "errors": null,_14 "fields": {_14 "mainOrderId": "MKP-123456789",_14 "franchiseOrderId": null_14 },_14 "message": "Order integrated successfully"_14}
Scenario 9: Order with pickup-in-point
To input a pickup-in-point order, where the customer’ll be responsible for retrieving the products in a specified store, you must do the following in the New Order Integration API request:
- Fill the
selectedDeliveryChannel
field with the valuepickup-in-point
. - Fill the
selectedAddresses
list with the pickup point address, instead of the customers’s, specifying:- In the
addressType
field the valuepickup
. - In the
addressId
field the pickup point’s ID in VTEX’s logistics system.
- In the
- Fill the
geoCoordinates
field with the geo coordinates from the pickup address. - The
isFob
field cannot be set totrue
if the order’s delivery type is pickup-in-point. - The
selectedSla
should be left empty forpickup-in-point
orders as well.
Response
_11{_11 "marketplaceOrderId": null,_11 "accountName": "connections",_11 "code": "SOI003",_11 "flow": "PlaceOrder",_11 "success": true,_11 "operationId": null,_11 "errors": null,_11 "fields": null,_11 "message": "Order successfully enqueued"_11}
Notification
_14{_14 "marketplaceOrderId": "123456789",_14 "accountName": "connections",_14 "code": "SOI001",_14 "flow": "PlaceOrder",_14 "success": true,_14 "operationId": "b830df0e-3377-4b44-9601-85ecfd848b41",_14 "errors": null,_14 "fields": {_14 "mainOrderId": "MKP-123456789",_14 "franchiseOrderId": null_14 },_14 "message": "Order integrated successfully"_14}
Scenario 10: Order with a franchise pickup-in-point (Multilevel Omnichannel Inventory)
To input a franchise pickup-in-point order, where the customer’ll be responsible for retrieving the products in a specified seller’s franchise store, you must do the following in the New Order Integration API request:
- Fill the
selectedDeliveryChannel
field with the valuepickup-in-point
. - Fill the
selectedAddresses
list with the pickup point address, instead of the customers’s, specifying:- In the
addressType
field the valuepickup
. - In the
addressId
field the pickup point’s ID in VTEX’s logistics system.
- In the
- Set the
allowFranchises
field totrue
. - Fill the
pickupAccountName
field, indicating from which account name the pickup point selected in the order is from, even if it’s from the main account. - Fill the
geoCoordinates
field with the geo coordinates from the pickup address. - The
isFob
field cannot be set to true if the order’s delivery type is pickup-in-point. - The
selectedSla
should be left empty forpickup-in-point
orders as well.
Response
_11{_11 "marketplaceOrderId": null,_11 "accountName": "connections",_11 "code": "SOI003",_11 "flow": "PlaceOrder",_11 "success": true,_11 "operationId": null,_11 "errors": null,_11 "fields": null,_11 "message": "Order successfully enqueued"_11}
Notification
_14{_14 "marketplaceOrderId": "123456789",_14 "accountName": "connections",_14 "code": "SOI001",_14 "flow": "PlaceOrder",_14 "success": true,_14 "operationId": "c1f00956-801c-4ab5-b343-b05c1d33863e",_14 "errors": null,_14 "fields": {_14 "mainOrderId": "MKP-123456789-01",_14 "franchiseOrderId": "MKT-MKP-123456789-01"_14 },_14 "message": "Order integrated successfully"_14}
Scenario 11: Order with taxes
To integrate orders with additional taxes values, in the New Order Integration API request, you need to fill in the taxData field, a list containing all taxes, one per SKU. If you don’t have the value individually by SKU, you can add only one item in the list, using one SKU ID from the order and adding all the taxes in field value.
Response
_11{_11 "marketplaceOrderId": null,_11 "accountName": "connections",_11 "code": "SOI003",_11 "flow": "PlaceOrder",_11 "success": true,_11 "operationId": null,_11 "errors": null,_11 "fields": null,_11 "message": "Order successfully enqueued"_11}
Notification
_14{_14 "marketplaceOrderId": "123456789",_14 "accountName": "connections",_14 "code": "SOI001",_14 "flow": "PlaceOrder",_14 "success": true,_14 "operationId": "7425f2ef-0849-4b73-94c7-355982119e51",_14 "errors": null,_14 "fields": {_14 "mainOrderId": "MKP-123456789",_14 "franchiseOrderId": null_14 },_14 "message": "Order integrated successfully"_14}
Scenario 12: Order with tracking hints
To integrate orders with label information, in the New Order Integration API request, you need to fill in the trackingHints field, a list containing all infos related to order label.
Response
_11{_11 "marketplaceOrderId": null,_11 "accountName": "connections",_11 "code": "SOI003",_11 "flow": "PlaceOrder",_11 "success": true,_11 "operationId": null,_11 "errors": null,_11 "fields": null,_11 "message": "Order successfully enqueued"_11}
Notification
_14{_14 "marketplaceOrderId": "123456789",_14 "accountName": "connections",_14 "code": "SOI001",_14 "flow": "PlaceOrder",_14 "success": true,_14 "operationId": "7425f2ef-0849-4b73-94c7-355982119e51",_14 "errors": null,_14 "fields": {_14 "mainOrderId": "MKP-123456789",_14 "franchiseOrderId": null_14 },_14 "message": "Order integrated successfully"_14}