{ "openapi": "3.0.0", "info": { "title": "Marketplace Protocol", "description": "The _Marketplace Protocol_ is a set of API requests and definitions to help you integrate external sellers into a VTEX marketplace as well as external marketplaces into VTEX sellers.\r\n\r\n## External Seller\r\n\r\nHere you will find the endpoints involved in the integration between a VTEX marketplace and an external seller. Note that some of these requests are typically sent by the seller while others are received.\r\n\r\n| **Request** | **From** | **To** |\r\n|-|-|-|\r\n| [Fulfillment simulation](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orderForms/simulation) | Marketplace | Seller |\r\n| [Order placement](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders) | Marketplace | Seller |\r\n| [Authorize fulfillment](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-sellerOrderId-/fulfill) | Marketplace | Seller |\r\n| [Marketplace order cancellation](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-orderId-/cancel) | Marketplace | Seller |\r\n| [Send invoice](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice) | Seller | Marketplace |\r\n| [Send tracking information](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-) | Seller | Marketplace |\r\n| [Update tracking status](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-/tracking) | Seller | Marketplace |\r\n| [Cancel order in marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/cancel) | Seller | Marketplace |\r\n\r\nFor a detailed explanation of the steps required to develop a custom connector to sell products from an external seller in your storefront, check out our complete [External Seller Integration Guide](https://developers.vtex.com/docs/guides/external-seller-integration-guide).\r\n\r\n\r\n## External Marketplace\r\n\r\nIn this section, you will find the endpoints involved in the VTEX integration between an external marketplace and a VTEX seller.\r\n\r\n\r\n| **Request** | **From** | **To** |\r\n|-|-|-|\r\n| [VTEX Mapper Registration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/connector/register) | External marketplace | VTEX system |\r\n| [Send Category Mapping to VTEX Mapper](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/categories/marketplace/-id-) | External marketplace | VTEX system |\r\n| [New Order Integration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/order-integration/orders) | External marketplace | VTEX system |\r\n| [Update Order Status](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#put-/api/order-integration/orders/status) | External marketplace | VTEX system |\r\n| [Fulfillment simulation - External Marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/checkout/pub/orderForms/simulation) | External marketplace | VTEX system |\r\n| [Place fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders) | External marketplace | VTEX Seller |\r\n| [Authorize dispatch for fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders/-orderId-/fulfill) | External marketplace | VTEX Seller |\r\n\r\n\r\nFor a detailed explanation of the steps required to develop a custom connector to become an external marketplace for VTEX sellers, check out our complete [External Marketplace Integration Guide](https://developers.vtex.com/docs/guides/external-marketplace-integration-guide).", "contact": {}, "version": "1.0" }, "servers": [ { "url": "https://{fulfillmentEndpoint}", "description": "Fulfillment Endpoint.", "variables": { "fulfillmentEndpoint": { "description": "This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", "default": "{fulfillmentEndpoint}" } } } ], "paths": { "/pvt/orderForms/simulation": { "post": { "tags": [ "External Seller" ], "summary": "Fulfillment simulation - external seller", "description": "This endpoint may be called upon by VTEX for fulfillment simulation in the external seller different contexts. See examples below.\n\nWhen a [price](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/price) or [inventory](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/inventory) 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.\n\nThe 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.\n\nIf the seller wishes to include other parameters in this call (like account name, or [sales channel](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV) ID), this should be done within their {fulfillmentEndpoint}. This path is then inserted in the marketplace's VTEX admin when [configuring a seller](https://help.vtex.com/en/tutorial/configurando-seller--tutorials_392). \n\nThe 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. \n\nThis call is also applied in the Storefront simulation scenario, in which case the request from VTEX does not send the parameters `country` and `postalCode`. \nThe call's payload can be adapted into two scenarios: \n\n- **Displaying items in the storefront**: the address information can be nulled in the request since they are not mandatory data for this context. \n- **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. \n \n## Request body example - Indexing simulation\n\n```\n{\n \"items\": [\n {\n \"id\": \"7908010136043\",\n \"quantity\": 1,\n \"seller\": \"1\",\n }\n ],\n \"isCheckedIn\": false,\n }\n``` \n## Request body example - Checkout simulation\n\n```\n{\n \"items\": [\n {\n \"id\": \"7908010136043\",\n \"quantity\": 1,\n \"seller\": \"1\",\n }\n ],\n \"postalCode\": \"22270-030\",\n \"country\": \"BRA\",\n }\n```\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "fulfillment-simulation", "parameters": [ { "$ref": "#/components/parameters/fulfillmentEndpoint" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/requestFulfillmentSimulation" }, "example": { "postalCode": "22270-030", "geoCoordinates": [ "-22.9443504" ], "country": "BRA", "items": [ { "id": "6", "quantity": 1, "seller": "01" } ], "sc": "1" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseFulfillmentSimulation" }, "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": "2014-03-01T22:58:28.143", "quantity": 1, "requestIndex": 0, "seller": "1", "unitMultiplier": 1 } ], "logisticsInfo": [ { "itemIndex": 0, "quantity": 1, "shipsTo": [ "BRA" ], "slas": [ { "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": "Juliana", "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": "Next to the unicorn statue", "geoCoordinates": [ 49.334934, 25.401705 ] }, "additionalInfo": "" } } ], "stockBalance": 199, "deliveryChannels": [ { "id": "delivery", "stockBalance": 179 }, { "id": "pickup-in-point", "stockBalance": 20 } ] } ], "postalCode": "80250000", "allowMultipleDeliveries": true } } } } }, "deprecated": false } }, "/pvt/orders": { "post": { "tags": [ "External Seller" ], "summary": "Order placement", "description": "This request is sent by VTEX to the external seller once the customer finishes their checkout, to let the seller know there is a newly placed order. It does that by calling the **Order Placement** endpoint, which needs to be implemented by the seller.\n\nThe marketplace will send information such as the items contained in the cart, the client’s profile data, the shipping data, and the payment data. With all that, the seller will be able to create the order in their store.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| VTEX Fulfilment | Fulfilment Resources | **Place Orders** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Create orders | Place Orders |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "operationId": "order-placement", "parameters": [ { "$ref": "#/components/parameters/fulfillmentEndpoint" }, { "$ref": "#/components/parameters/content-length" }, { "$ref": "#/components/parameters/authorization" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/accept-enconding" }, { "$ref": "#/components/parameters/vtexOperationID" }, { "$ref": "#/components/parameters/forwardedProto" }, { "$ref": "#/components/parameters/forwardedFor" }, { "$ref": "#/components/parameters/vtexCacheClientBypass" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/traceparent" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/orderPlacement" }, "example": { "marketplaceOrderId": "1138342255777-01", "marketplaceServicesEndpoint": "https://marketplaceservicesendpoint.myvtex.com/", "marketplacePaymentValue": 2499, "items": [ { "id": "123456789abc", "quantity": 1, "seller": "seller-example", "commission": 0, "freightCommission": 0, "price": 2499, "bundleItems": [ { "id": 12, "quantity": 2 }, { "id": 5, "quantity": 1 } ], "itemsAttachment": [ { "id": "attachment-1", "name": "Product Manual", "url": "https://example.com/manual.pdf" } ], "attachments": [ { "id": "attachment-2", "name": "Product Image", "url": "https://example.com/image.jpg" } ], "priceTags": [ { "identifier": "1234abc-5678b-1234c", "isPercentual": false, "name": "discount@name-1234abc-5678b-1234c", "rawValue": 12, "value": 1200 } ], "measurementUnit": "g", "unitMultiplier": 1, "isGift": false } ], "paymentData": null, "clientProfileData": { "email": "customer@examplemail.com", "firstName": "first-name", "lastName": "last-name", "documentType": "cpf", "document": "123456789", "phone": "+55110988887777", "corporateName": null, "tradeName": null, "corporateDocument": null, "stateInscription": null, "corporatePhone": null, "isCorporate": false }, "shippingData": { "address": { "addressType": "residential", "receiverName": "receiver-name", "addressId": "Home", "postalCode": "12345-000", "city": "Rio de Janeiro", "state": "Rio de Janeiro", "country": "BRA", "street": "Praia de Botafogo", "number": "300", "neighborhood": "Botafogo", "complement": "3rd floor", "reference": "Grey building", "geoCoordinates": [ "49.334934", "25.401705" ] }, "logisticsInfo": [ { "itemIndex": 0, "selectedSla": "Express", "lockTTL": "8d", "shippingEstimate": "7d", "price": 1099, "deliveryWindow": { "startDateUtc": "2016-04-20T08:00:00+00:00", "endDateUtc": "2016-04-20T12:00:00+00:00", "listPrice": 10 } } ], "updateStatus": "updated" }, "marketingData": { "utmSource": "Facebook", "utmMedium": "CPC", "utmCampaign": "Black friday", "utmiPage": "utmi_page-example", "utmiPart": "utmi_part-exmaple", "utmiCampaign": "utmi_campaign-exmaple" }, "openTextField": "open-text-example" } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseOrderPlacement" }, "example": { "marketplaceOrderId": "959311095", "orderId": "7890", "followUpEmail": "seller@example.com", "items": [ { "id": "2002495", "quantity": 1, "seller": "1", "commission": 0, "freightCommission": 0, "price": 2499, "bundleItems": [], "itemAttachment": { "name": null, "content": {} }, "attachments": [], "priceTags": [], "measurementUnit": "g", "unitMultiplier": 1, "isGift": false } ], "clientProfileData": { "email": "customer@examplemail.com.br", "firstName": "John", "lastName": "Smith", "documentType": "taxpayer registration number", "document": "33333333333", "phone": "+55110988887777", "corporateName": null, "tradeName": null, "corporateDocument": null, "stateInscription": null, "corporatePhone": null, "isCorporate": false, "userProfileId": null }, "shippingData": { "address": { "addressType": "residencial", "receiverName": "John Smith", "addressId": "Home", "postalCode": "12345-000", "city": "Rio de Janeiro", "state": "RJ", "country": "BRA", "street": "Praia de Botafogo", "number": "300", "neighborhood": "Botafogo", "complement": "3rd floor", "reference": "Grey building", "geoCoordinates": [ "49.334934", "25.401705" ] }, "logisticsInfo": [ { "itemIndex": 0, "selectedSla": "Express", "lockTTL": "8d", "shippingEstimate": "7d", "price": 1099, "deliveryWindow": { "startDateUtc": "2016-04-20T08:00:00+00:00", "endDateUtc": "2016-04-20T12:00:00+00:00", "listPrice": 10 } } ] }, "customData": { "openTextField": null, "marketingData": { "utmSource": "buscape", "utmMedium": "", "utmCampaign": "freeshipping", "utmiPage": "_", "utmiPart": "BuscaFullText", "utmiCampaign": "artscase for iphone 5" } }, "paymentData": null, "allowMultipleDeliveries": true } } } } } } }, "/pvt/orders/{sellerOrderId}/fulfill": { "post": { "tags": [ "External Seller" ], "summary": "Authorize fulfillment", "description": "This request is sent from VTEX to the seller after the payment is approved, to notify them that the fulfillment process can start.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "authorize-fulfillment", "parameters": [ { "$ref": "#/components/parameters/fulfillmentEndpoint" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/sellerOrderId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/requestOrderId" }, "example": { "marketplaceOrderId": "1138342255777-01", "marketplaceOrderGroup": "group-123", "cancellationRequestId": "85838ab408514b52aa139e4236ce0c43", "cancellationRequestDate": "2024-03-04T15:45:02.1306363+00:00", "reason": "Incorrect product", "requestedByUser": true, "paymentData": { "payments": [ { "paymentSystem": "1", "paymentSystemName": "Visa", "value": 32499, "installments": 1, "referenceValue": 32499, "group": "creditCard" } ], "connectorResponses": { "Message": "Processing Payment", "tid": "2212318890", "authorizationId": "333333", "status": "Approved", "delayToAutoSettle": 432000, "ReturnCode": "6205", "nsu": "1234567891111110", "code": "2000", "message": "Transaction approved", "acquirer": "Visa", "authId": "769670", "paymentId": "1138342255777", "delayToAutoSettleAfterAntifraud": "12000" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/repsonseOrderId" }, "example": { "date": "2014-10-06 18:52:00", "marketplaceOrderId": "1138342255777-01", "orderId": "959311095", "receipt": "e39d05f9-0c54-4469-a626-8bb5cff169f8" } } } } } } }, "/pvt/orders/{orderId}/cancel": { "post": { "tags": [ "External Seller" ], "summary": "Marketplace order cancellation", "description": "This request may be sent from VTEX to the external seller in case of order cancelation. For that, the seller will need to implement the Marketplace order cancellation endpoint. Whenever this request is received by the seller, the order should be canceled and the fulfillment flow should not proceed. \n\nFor the seller to: \n\n- **Evaluate a cancellation request:** it is possible to send an empty body as a response to the cancellation request, meaning that the seller is evaluating whether to proceed with the cancellation or not. \n\n- **Confirm the cancellation request:** it is possible to confirm the order cancellation by the marketplace by responding to the call with a body including only one information: the `marketplaceOrderId`, which identifies the order in the marketplace. The seller should use this ID to trigger the cancellation of the corresponding order. The seller should then respond with the same `marketplaceOrderId` and also with the `orderId`, which identifies the order in the seller, the date and time of the notification receipt, and a protocol code that confirms the receipt of the request (which may have the value `null`). \n\n- **Refuse a cancellation request:** it is possible to to [send the Invoice](https://developers.vtex.com/vtex-rest-api/reference/external-seller#send-invoice), meaning that the cancellation has been denied, and the flow continues to the [Order Invoicing](https://developers.vtex.com/vtex-rest-api/docs/external-seller-integration-connector#order-invoicing) step, and the ones that follow it. \n\n>⚠️ This call should be made twice: once for the *Evaluate cancellation request* scenario, and a second time to *Confirm cancellation* or *Refuse cancellation*.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Checkout | CheckoutResources | **Order Cancellation** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Cancela Pedidos | Order Cancellation |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "operationId": "mkp-order-cancellation", "parameters": [ { "$ref": "#/components/parameters/fulfillmentEndpoint" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/orderId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/requestOrderId" }, "example": { "marketplaceOrderId": "1138342255777-01", "marketplaceOrderGroup": "group-123", "cancellationRequestId": "85835ab408514b52aa139e4236ce0c33", "cancellationRequestDate": "2024-03-04T15:45:02.1306363+00:00", "reason": "Out of stock", "requestedByUser": true } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/repsonseOrderId" }, "example": { "date": "2019-05-09 15:31:23", "marketplaceOrderId": "959311095", "orderId": "1138342255777-01", "receipt": "e39d05f9-0c54-4469-a626-8bb5cff169f8" } } } } } } } }, "security": [ { "appKey": [], "appToken": [] } ], "components": { "schemas": { "fulfillmentItem": { "description": "Details of an item to be fulfilled.", "required": [ "id", "quantity", "seller" ], "type": "object", "properties": { "id": { "type": "string", "description": "SKU ID." }, "quantity": { "type": "integer", "description": "Quantity of items of the SKU in the cart." }, "seller": { "type": "string", "description": "ID of the seller registered in VTEX." } } }, "orderPlacement": { "description": "Informations related to the placement of an order.", "type": "object", "properties": { "marketplaceOrderId": { "type": "string", "description": "Identifies the order in the marketplace.", "example": "1138342255777-01" }, "marketplaceServicesEndpoint": { "type": "string", "description": "Endpoint sent by VTEX to the seller, that will be used to send the invoice and tracking data to the marketplace. This endpoint will also be used in [change order in Multilevel Omnichannel Inventory](https://developers.vtex.com/docs/guides/change-orders-multilevel-omnichannel-inventory-external-marketplaces#implementators) operations in external marketplaces.", "example": "https://marketplaceservicesendpoint.myvtex.com/" }, "marketplacePaymentValue": { "type": "integer", "description": "Amount that the marketplace agrees to pay to the seller. The last two digits are the cents. For example, $24.99 is represented 2499.", "example": 2499 }, "items": { "type": "array", "description": "Array of objects.", "items": { "description": "Data about each SKU in the cart.", "type": "object", "properties": { "id": { "type": "string", "description": "SKU ID.", "example": "123456789abc" }, "quantity": { "type": "integer", "description": "Quantity of the item.", "example": 1 }, "seller": { "type": "string", "description": "ID of the seller registered in VTEX.", "example": "seller-example" }, "commission": { "type": "integer", "description": "Comission.", "example": 0 }, "freightCommission": { "type": "integer", "description": "Freight comission.", "example": 0 }, "price": { "type": "integer", "description": "SKU price. The last two digits are the cents. For example, $24.99 is represented 2499.", "example": 2499 }, "bundleItems": { "type": "array", "description": "Information on services sold along with the SKU. Example: a gift package.", "items": { "$ref": "#/components/schemas/bundleItemsItem" } }, "itemsAttachment": { "type": "array", "description": "Attachments sold with the SKU.", "items": { "$ref": "#/components/schemas/itemAttachment" } }, "attachments": { "type": "array", "description": "Array containing information on attachments.", "items": { "type": "object", "description": "Attachment information.", "properties": { "id": { "type": "string", "description": "Unique identifier of the attachment.", "example": "attachment-1" }, "name": { "type": "string", "description": "Name of the attachment.", "example": "Product Image" }, "url": { "type": "string", "description": "URL of the attachment.", "example": "https://example.com/image.jpg" } } } }, "priceTags": { "type": "array", "description": "Array of price tags, each of which, modifies the price in some way, like discounts or rates that apply to the item in the context of the order.", "items": { "description": "Details of a price tag affecting the item's price.", "type": "object", "properties": { "identifier": { "type": "string", "description": "Price tag identifier.", "example": "1234abc-5678b-1234c" }, "isPercentual": { "type": "boolean", "description": "`true` if price tag value is applied through a percentage.", "example": false }, "name": { "type": "string", "description": "Price tag name.", "example": "discount@name-1234abc-5678b-1234c" }, "rawValue": { "type": "integer", "description": "Price tag value.", "example": -12 }, "value": { "type": "integer", "description": "Price tag raw value.", "example": -1200 } } } }, "measurementUnit": { "type": "string", "description": "SKU measurement unit.", "example": "g" }, "unitMultiplier": { "type": "integer", "description": "SKU unit multiplier.", "example": 1 }, "isGift": { "type": "boolean", "description": "Indicates if the item is a gift (`true`).", "example": true } } } }, "paymentData": { "type": "object", "description": "In other contexts, this field tipically holds an object with payment information. However, since the payment is processed by the marketplace, it will be sent to the seller as `null` in this context.", "nullable": true, "example": null }, "clientProfileData": { "type": "object", "description": "Customer's profile information.", "required": [ "email", "firstName", "lastName", "documentType", "document", "isCorporate" ], "properties": { "email": { "type": "string", "description": "Customer's email address.", "example": "customer@examplemail.com" }, "firstName": { "type": "string", "description": "Customer's first name.", "example": "first-name" }, "lastName": { "type": "string", "description": "Customer's last name.", "example": "last-name" }, "documentType": { "type": "string", "description": "Type of the document informed by the customer.", "example": "cpf" }, "document": { "type": "string", "description": "Document number informed by the customer.", "example": "123456789" }, "phone": { "type": "string", "description": "Customer's phone number.", "example": "+55110988887777" }, "corporateName": { "type": "string", "description": "Company name, if the customer is a legal entity.", "example": "company-name", "nullable": true }, "tradeName": { "type": "string", "description": "Trade name, if the customer is a legal entity.", "example": "trade-name", "nullable": true }, "corporateDocument": { "type": "string", "description": "Corporate document, if the customer is a legal entity.", "example": "12345678000100", "nullable": true }, "stateInscription": { "type": "string", "description": "State inscription, if the customer is a legal entity.", "example": "12345678", "nullable": true }, "corporatePhone": { "type": "string", "description": "Corporate phone number, if the customer is a legal entity.", "example": "+551100988887777", "nullable": true }, "isCorporate": { "type": "boolean", "description": "`true` if the customer is a legal entity.", "default": false, "example": false, "nullable": true } } }, "shippingData": { "type": "object", "description": "Shipping information.", "properties": { "address": { "type": "object", "description": "Shipping address.", "required": [ "addressType", "receiverName", "postalCode", "city", "state", "country", "street", "neighborhood", "number" ], "properties": { "addressType": { "type": "string", "description": "Type of address. For example, `Residential` or `Pickup`, among others.", "example": "residential" }, "receiverName": { "type": "string", "description": "Name of the person who is going to receive the order.", "example": "receiver-name" }, "addressId": { "type": "string", "description": "Address ID.", "example": "Home" }, "postalCode": { "type": "string", "description": "Postal Code.", "example": "12345-000" }, "city": { "type": "string", "description": "City of the shipping address.", "example": "Rio de Janeiro" }, "state": { "type": "string", "description": "State of the shipping address.", "example": "Rio de Janeiro" }, "country": { "type": "string", "description": "Three letter ISO code of the country of the shipping address.", "example": "BRA" }, "street": { "type": "string", "description": "Street of the shipping address.", "example": "Praia de Botafogo" }, "number": { "type": "string", "description": "Number of the building, house or apartment in the shipping address.", "example": "300" }, "neighborhood": { "type": "string", "description": "Neighborhood of the shipping address.", "example": "Botafogo" }, "complement": { "type": "string", "description": "Complement to the shipping address in case it applies.", "example": "3rd floor" }, "reference": { "type": "string", "description": "Complement that might help locate the shipping address more precisely in case of delivery.", "example": "Grey building" }, "geoCoordinates": { "type": "array", "description": "Geographic coordinates of the delivery address. This may be used instead of the postalCode, in case the marketplace is configured to accept geolocation. Example of value: `[-22.9443504,-43.1825635]`.", "items": { "description": "Coordinate value.", "type": "string", "example": "00.00000000" } } } }, "logisticsInfo": { "type": "array", "description": "Array of objects containing logistics information of each item.", "items": { "description": "Logistics information for a specific item.", "type": "object", "required": [ "itemIndex", "selectedSla", "price" ], "properties": { "itemIndex": { "type": "integer", "description": "Index of the item in the `items` array, starting from 0.", "example": 0 }, "selectedSla": { "type": "string", "description": "Selected shipping option.", "example": "Express" }, "lockTTL": { "type": "string", "description": "Logistics reservation waiting time.", "example": "8d" }, "shippingEstimate": { "type": "string", "description": "Estimated time until delivery for the item.", "example": "7d" }, "price": { "type": "integer", "description": "Shipping price for the item. Does not account for the whole order's shipping price.", "example": 1099 }, "deliveryWindow": { "type": "object", "description": "Scheduled delivery window information, in case it applies to the item.", "properties": { "startDateUtc": { "type": "string", "description": "Scheduled delivery window start date in UTC.", "example": "2016-04-20T08:00:00+00:00" }, "endDateUtc": { "type": "string", "description": "Scheduled delivery window end date in UTC.", "example": "2016-04-20T12:00:00+00:00" }, "listPrice": { "type": "number", "description": "Scheduled delivery window list price.", "example": 10 } } } } } }, "updateStatus": { "type": "string", "description": "Indicate whether this object's information is up to date according to the order's items. An order can not be placed if `\"outdated\"`.", "example": "updated" } } }, "marketingData": { "type": "object", "description": "Marketing tracking data. If the order has no tracking data, the value will be `null`.", "properties": { "utmSource": { "type": "string", "description": "UTM source.", "example": "Facebook" }, "utmMedium": { "type": "string", "description": "UTM medium.", "example": "CPC" }, "utmCampaign": { "type": "string", "description": "UTM campaign.", "example": "Black friday" }, "utmiPage": { "type": "string", "description": "utmi_page (internal utm).", "example": "utmi_page-example" }, "utmiPart": { "type": "string", "description": "utmi_part (internal utm).", "example": "utmi_part-exmaple" }, "utmiCampaign": { "type": "string", "description": "utmi_campaign (internal utm).", "example": "utmi_campaign-exmaple" } } }, "openTextField": { "type": "string", "description": "Optional field meant to hold additional information about the order. We recommend using this field for text, not data formats such as `json` even if escaped. For that purpose, see [Creating customizable fields](https://developers.vtex.com/vtex-rest-api/docs/creating-customizable-fields-in-the-cart-with-checkout-api-1).", "example": "open-text-example" } } }, "responseOrderPlacement": { "description": "Expected response from the Order Placement endpoint.", "type": "object", "properties": { "marketplaceOrderId": { "description": "Number of the order in the marketplace.", "type": "string" }, "orderId": { "description": "Order number.", "type": "string" }, "followUpEmail": { "description": "Email for contact with the store (seller).", "type": "string" }, "items": { "description": "List of order items.", "type": "array", "items": { "description": "Details of an order item.", "type": "object", "properties": { "id": { "type": "string", "description": "SKU ID." }, "quantity": { "type": "integer", "description": "Quantity of the item." }, "seller": { "type": "string", "description": "ID of the seller registered in VTEX." }, "commission": { "type": "integer", "description": "Comission." }, "freightCommission": { "type": "integer", "description": "Freight comission." }, "price": { "type": "number", "description": "SKU price. The last two digits are the cents. For example, $24.99 is represented 2499.", "example": 2499 }, "bundleItems": { "type": "array", "description": "Information on services sold along with the SKU. Example: a gift package.", "items": { "$ref": "#/components/schemas/bundleItemsItem" } }, "itemsAttachment": { "type": "array", "description": "Attachments sold with the SKU.", "items": { "$ref": "#/components/schemas/itemAttachment" } }, "attachments": { "type": "array", "description": "Array containing information on attachments.", "items": { "type": "object", "description": "Attachment information.", "properties": { "id": { "type": "string", "description": "Unique identifier of the attachment." }, "name": { "type": "string", "description": "Name of the attachment." }, "url": { "type": "string", "description": "URL of the attachment." } } } }, "priceTags": { "type": "array", "description": "Array of price tags. Each one modifies the price in some way, like discounts or rates that apply to the item in the context of the order.", "items": { "description": "Details of a price tag affecting the item's price.", "type": "object", "properties": { "identifier": { "type": "string", "description": "Price tag identifier." }, "isPercentual": { "type": "boolean", "description": "`true` if price tag value is applied through a percentage." }, "name": { "type": "string", "description": "Price tag name." }, "rawValue": { "type": "integer", "description": "Price tag value." }, "value": { "type": "integer", "description": "Price tag raw value." } } } }, "measurementUnit": { "type": "string", "description": "SKU measurement unit." }, "unitMultiplier": { "type": "integer", "description": "SKU unit multiplier." }, "isGift": { "type": "boolean", "description": "`true` if the item is a gift." } } } }, "clientProfileData": { "description": "Customer's data.", "type": "object", "properties": { "email": { "type": "string", "description": "Customer's email address." }, "firstName": { "type": "string", "description": "Customer's first name." }, "lastName": { "type": "string", "description": "Customer's last name." }, "documentType": { "type": "string", "description": "Type of the document informed by the customer." }, "document": { "type": "string", "description": "Document number informed by the customer." }, "phone": { "type": "string", "description": "Customer's phone number." }, "corporateName": { "type": "string", "description": "Company name, if the customer is a legal entity.", "nullable": true }, "tradeName": { "type": "string", "description": "Trade name, if the customer is a legal entity.", "nullable": true }, "corporateDocument": { "type": "string", "description": "Corporate document, if the customer is a legal entity.", "nullable": true }, "stateInscription": { "type": "string", "description": "State inscription, if the customer is a legal entity.", "nullable": true }, "corporatePhone": { "type": "string", "description": "Corporate phone number, if the customer is a legal entity.", "nullable": true }, "isCorporate": { "type": "boolean", "description": "`true` if the customer is a legal entity.", "default": false, "nullable": true } } }, "shippingData": { "description": "Shipping information.", "type": "object", "properties": { "address": { "type": "object", "description": "Shipping address.", "required": [ "addressType", "receiverName", "postalCode", "city", "state", "country", "street", "neighborhood", "number" ], "properties": { "addressType": { "type": "string", "description": "Type of address. For example, `Residential` or `Pickup`, among others." }, "receiverName": { "type": "string", "description": "Name of the person who is going to receive the order." }, "addressId": { "type": "string", "description": "Address ID." }, "postalCode": { "type": "string", "description": "Postal Code." }, "city": { "type": "string", "description": "City of the shipping address." }, "state": { "type": "string", "description": "State of the shipping address." }, "country": { "type": "string", "description": "Three letter ISO code of the country of the shipping address." }, "street": { "type": "string", "description": "Street of the shipping address." }, "number": { "type": "string", "description": "Number of the building, house or apartment in the shipping address." }, "neighborhood": { "type": "string", "description": "Neighborhood of the shipping address." }, "complement": { "type": "string", "description": "Complement to the shipping address in case it applies." }, "reference": { "type": "string", "description": "Complement that might help locate the shipping address more precisely in case of delivery." }, "geoCoordinates": { "type": "array", "description": "Geographic coordinates of the delivery address. This may be used instead of the postalCode, in case the marketplace is configured to accept geolocation. Example of value: `[-22.9443504,-43.1825635]`.", "items": { "description": "Coordinate value.", "type": "string" } } } }, "logisticsInfo": { "type": "array", "description": "Array of objects containing logistics information of each item.", "items": { "description": "Logistics information for a specific item.", "type": "object", "required": [ "itemIndex", "selectedSla", "price" ], "properties": { "itemIndex": { "type": "integer", "description": "Index of the item in the `items` array, starting from 0." }, "selectedSla": { "type": "string", "description": "Selected shipping option." }, "lockTTL": { "type": "string", "description": "Logistics reservation waiting time." }, "shippingEstimate": { "type": "string", "description": "Estimated time until delivery for the item." }, "price": { "type": "integer", "description": "Shipping price for the item. Does not account for the whole order's shipping price." }, "deliveryWindow": { "type": "object", "description": "Scheduled delivery window information, in case it applies to the item.", "properties": { "startDateUtc": { "type": "string", "description": "Scheduled delivery window start date in UTC." }, "endDateUtc": { "type": "string", "description": "Scheduled delivery window end date in UTC." }, "listPrice": { "type": "number", "description": "Scheduled delivery window list price.", "example": 10 } } } } } } } }, "paymentData": { "type": "object", "description": "In other contexts, this field tipically holds an object with payment information. However, since the payment is processed by the marketplace, it will be sent to the seller as `null` in this context.", "nullable": true }, "customData": { "description": "Custom data for the order.", "type": "object" }, "allowMultipleDeliveries": { "description": "Flag for permission of multiple deliveries.", "type": "boolean" } } }, "bundleItemsItem": { "description": "An item included in a bundle, representing a service or product.", "type": "object", "properties": { "type": { "type": "string", "description": "Service type." }, "id": { "type": "integer", "description": "Service identifier." }, "name": { "type": "string", "description": "Service name." }, "price": { "type": "integer", "description": "Service price. The last two digits are the cents." } } }, "itemAttachment": { "type": "object", "description": "An attachment associated with an item, containing additional information or customization requested by the customer.", "properties": { "name": { "type": "string", "description": "Attachment name." }, "content": { "type": "string", "description": "Content referring to the customization requested by the customer." } } }, "requestFulfillmentSimulation": { "description": "This request body represents a fulfillmentsimulation, which may involve delivering items to a specified address. It is used to test the process of fulfilling orders without actually placing them.", "required": [ "postalCode" ], "type": "object", "properties": { "postalCode": { "type": "string", "description": "Delivery address postal code. 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.", "example": "12345678" }, "geoCoordinates": { "type": "array", "description": "Geographic coordinates of the delivery address. This may be used instead of the postalCode, in case the marketplace is configured to accept geolocation. Example of value: `[-22.9443504,-43.1825635]`.", "items": { "description": "Coordinate value.", "type": "string" } }, "country": { "type": "string", "description": "ISO 3-digit code of the country where the delivery address is located. 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." }, "items": { "type": "array", "description": "Array containing the cart items.", "items": { "$ref": "#/components/schemas/fulfillmentItem" } }, "sc": { "type": "string", "description": "Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) associated to the seller account created." } } }, "responseFulfillmentSimulation": { "title": "Response body", "description": "Expected response body of fulfillment simulation.", "type": "object", "required": [ "country", "items", "logisticsInfo", "postalCode" ], "properties": { "country": { "title": "Country", "description": "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.", "type": "string" }, "items": { "title": "Items", "description": "Contains the data about each SKU in the cart.", "type": "array", "items": { "title": "Items", "description": "Contains the data about each SKU in the cart.", "type": "object", "required": [ "id", "listPrice", "measurementUnit", "merchantName", "offerings", "price", "priceTags", "priceValidUntil", "quantity", "requestIndex", "seller", "unitMultiplier" ], "properties": { "id": { "title": "id", "description": "SKU ID.", "type": "string" }, "listPrice": { "title": "listPrice", "description": "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.", "type": "integer" }, "measurementUnit": { "title": "measurementUnit", "description": "SKU’s measurement unit.", "type": "string" }, "merchantName": { "title": "merchantName", "description": "Name of the marketplace, used to guide payments. This field should be nulled if the marketplace is responsible for processing payments. Check out our [​​Payments in VTEX marketplaces](https://help.vtex.com/en/tutorial/payments-in-vtex-marketplaces--2kYOfWCZYweJkYl18bw9yD) article to know more.", "type": "string" }, "offerings": { "title": "offerings", "description": "Services that may be offered for this SKU. example 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": "array", "items": { "title": "offerings", "description": "Services that may be offered for this SKU. example 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": "object", "required": [ "type", "id", "name", "price" ], "properties": { "type": { "title": "type", "description": "Type of the service.", "type": "string" }, "id": { "title": "id", "description": "Service ID.", "type": "string" }, "name": { "title": "name", "description": "Service name.", "type": "string" }, "price": { "title": "price", "description": "Service price. The last two digits are the cents.", "type": "integer" } } } }, "price": { "title": "price", "description": "Actual selling price of the SKU. Don’t separate the decimal places. The last two digits are the cents.", "type": "integer" }, "priceTags": { "title": "priceTags", "description": "List with the promotions applied to the SKU.", "type": "array", "items": { "title": "priceTags", "description": "Promotions applied to the SKU.", "type": "string" } }, "priceValidUntil": { "title": "priceValidUntil", "description": "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.", "type": "string", "nullable": true }, "quantity": { "title": "quantity", "description": "Quantity of the item. The seller should send the quantity that was indicated in the request, or the maximum quantity possible.", "type": "integer", "default": 0 }, "requestIndex": { "title": "requestIndex", "description": "Position of this item in the original array (request).", "type": "integer" }, "seller": { "title": "seller", "description": "ID of the seller as registered in VTEX. You should send the same value that came in the request.", "type": "string" }, "unitMultiplier": { "title": "unitMultiplier", "description": "SKU unit multiplier. The default value is 1.", "type": "integer" } } } }, "logisticsInfo": { "title": "logisticsInfo", "description": "Array that contains the data regarding the delivery methods and stock for each item. If all products are unavailable, this field should return empty.", "type": "array", "items": { "description": "Description of each logistics data object.", "type": "object", "required": [ "itemIndex", "quantity", "shipsTo", "slas", "stockBalance", "deliveryChannels" ], "properties": { "itemIndex": { "title": "itemIndex", "description": "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`.", "type": "integer" }, "quantity": { "title": "quantity", "description": "Quantity of the item. The seller should send the quantity that was indicated in the request, or the maximum quantity possible.", "type": "integer" }, "shipsTo": { "title": "shipsTo", "description": "ISO 3-digit code of the countries to where the SKU is delivered.", "type": "array", "items": { "title": "shipsTo", "description": "Array of country codes.", "type": "string" } }, "slas": { "title": "slas", "description": "Contains the available delivery methods.", "type": "array", "items": { "title": "slas", "description": "Object with delivery methods information.", "type": "object", "required": [ "id", "deliveryChannel", "name", "price", "shippingEstimate", "availableDeliveryWindows", "pickupStoreInfo" ], "properties": { "id": { "title": "id", "description": "Identifier of the delivery method.", "type": "string" }, "deliveryChannel": { "title": "deliveryChannel", "description": "Type of delivery channel. The values that are possible are: `pickup-in-point` for pickup point and `delivery` for regular delivery.", "type": "string" }, "name": { "title": "name", "description": "Name of the delivery method.", "type": "string" }, "price": { "title": "price", "description": "Delivery price. The two last digits are the cents.", "type": "integer" }, "shippingEstimate": { "title": "shippingEstimate", "description": "Time estimated for the delivery. Possible suffixes are `bd` for *business day* , `h` for *hours*, and `m` for *minutes*.", "type": "string" }, "availableDeliveryWindows": { "title": "availableDeliveryWindows", "description": "Contains the delivery windows available for the SLA.", "type": "array", "items": { "title": "availableDeliveryWindows", "description": "Object with delivery windows information.", "type": "object", "required": [ "startDateUtc", "endDateUtc", "price" ], "properties": { "startDateUtc": { "title": "startDateUtc", "description": "Start date of the delivery window.", "type": "string" }, "endDateUtc": { "title": "endDateUtc", "description": "End date of the delivery window.", "type": "string" }, "price": { "title": "price", "description": "Extra price for scheduled delivery. The last two digits are the cents.", "type": "integer" } } } }, "pickupStoreInfo": { "title": "pickupStoreInfo", "description": "Contains the data about the pickup point. If you do not want to send this, use the value `null`.", "type": "object", "nullable": true, "required": [ "isPickupStore", "friendlyName", "address", "additionalInfo" ], "properties": { "isPickupStore": { "title": "isPickupStore", "description": "`true` if it is a pickup point.", "type": "boolean" }, "friendlyName": { "title": "friendlyName", "description": "Friendly name of the pickup point.", "type": "string" }, "address": { "title": "address", "description": "Address data of the pickup point.", "type": "object", "required": [ "addressType", "receiverName", "addressId", "postalCode", "city", "state", "country", "street", "number", "neighborhood", "complement", "reference", "geoCoordinates" ], "properties": { "addressType": { "title": " addressType", "description": "The possible value is pickup.", "type": "string" }, "receiverName": { "title": "receiverName", "description": "Name of the person who will receive the product. May be sent as `null`.", "type": "string", "nullable": true }, "addressId": { "title": "addressId", "description": "Identifies the pickup point.", "type": "string" }, "postalCode": { "title": "postalCode", "description": "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.", "type": "string" }, "city": { "title": "city", "description": "Pickup point's city.", "type": "string" }, "state": { "title": "state", "description": "Pickup point's state.", "type": "string" }, "country": { "title": "country", "description": "3-digit ISO code of the country where the pickup point is located.", "type": "string" }, "street": { "title": "street", "description": "Street where the pickup point is located.", "type": "string" }, "number": { "title": "number", "description": "Address number of the pickup point.", "type": "string" }, "neighborhood": { "title": "neighborhood", "description": "Neighborhood where the pickup point is located.", "type": "string" }, "complement": { "title": "complement", "description": "Complement of the pickup point address.", "type": "string" }, "reference": { "title": "reference", "description": "A reference for the pickup point address.", "type": "string", "nullable": true }, "geoCoordinates": { "title": "geoCoordinates", "description": "Contains the geographic coordinates of the pickup point.", "type": "array", "items": { "title": "geoCoordinates", "description": "Contains the geographic coordinates of the pickup point.", "type": "number", "example": 25.401705 } } } }, "additionalInfo": { "title": "additionalInfo", "description": "Description or extra information about the pickup point.", "type": "string" } } } } } }, "stockBalance": { "title": "stockBalance", "description": "Stock balance of the SKU.", "type": "integer" }, "deliveryChannels": { "title": "deliveryChannels", "description": "Array contains the stock balance for each channel.", "type": "array", "items": { "title": "deliveryChannels", "description": "Object containing ID and stockbalance of each delivery channel.", "type": "object", "required": [ "id", "stockBalance" ], "properties": { "id": { "title": "id", "description": "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.", "type": "string" }, "stockBalance": { "title": "stockBalance", "description": "Stock balance for the channel type selected in the previous field.", "type": "integer" } } } } } } }, "postalCode": { "title": "postalCode", "description": "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.", "type": "string" }, "allowMultipleDeliveries": { "description": "Flag for permission of multiple deliveries.", "type": "boolean" } } }, "requestOrderId": { "description": "Details related to a request for an order ID, which is used to trigger the fulfillment process of the corresponding order.", "required": [ "marketplaceOrderId", "marketplaceOrderGroup", "cancellationRequestDate", "cancellationRequestId", "reason", "requestedByUser" ], "type": "object", "properties": { "marketplaceOrderId": { "type": "string", "description": "Identifies the order. The seller should use this ID to trigger the fulfillment process of the corresponding order." }, "marketplaceOrderGroup":{ "type": "string", "description": "Identifies the group to which the order belongs. Useful for orders placed on marketplaces that operate with the [Multilevel Omnichannel Inventory](https://help.vtex.com/en/tutorial/multilevel-omnichannel-inventory--7M1xyCZWUyCB7PcjNtOyw4) structure." }, "cancellationRequestId":{ "type": "string", "description": "Unique identifier of the cancellation request on the platform." }, "cancellationRequestDate":{ "type": "string", "description": "Date and time the platform processed the cancellation request, in this format: `YYYY-MM-DDThh:mm:ss.SSSSSSS+00:00`." }, "reason": { "type": "string", "description": "Brief explanation of why the order is being canceled." }, "requestedByUser":{ "type": "boolean", "description": "When set as `true`, the cancellation was requested by the shopper, and when set as `false`, the cancellation was not requested by the shopper." }, "paymentData": { "type": "object", "description": "Payments information.", "properties": { "payments": { "type": "array", "description": "Array containing information about payments.", "items": { "type": "object", "description": "Information about a payment.", "properties": { "paymentSystem": { "type": "string", "description": "Payment system ID." }, "paymentSystemName": { "type": "string", "description": "Payment system name." }, "value": { "type": "integer", "description": "Order total payment value in cents." }, "installments": { "type": "integer", "description": "Number of payment installments." }, "referenceValue": { "type": "integer", "description": "Total payment reference value in cents." }, "group": { "type": "string", "description": "Transaction payment method, which can be credit card, debit card, bank invoice, promissory, gift card or pix (`instantPayment`).", "enum": [ "creditCard", "debitCard", "bankInvoice", "promissory", "giftCard", "instantPayment" ] } } } }, "connectorResponses": { "$ref": "#/components/schemas/ConnectorResponses" } } } } }, "repsonseOrderId": { "type": "object", "description": "Details related to an order, including the order approval date, marketplace order ID, order number, and order receipt code.", "properties": { "date": { "type": "string", "title": "Date", "description": "Order approval date." }, "marketplaceOrderId": { "type": "string", "title": "Marketplace Order Id", "description": "Identifies the order. The seller should use this ID to trigger the fulfillment process of the corresponding order." }, "orderId": { "type": "string", "title": "Order Id", "description": "Order number." }, "receipt": { "type": "string", "description": "Order receipt code.", "title": "Receipt" } } }, "ConnectorResponses": { "type": "object", "description": "Payment provider (connector) responses. The fields within this object can vary according to the order payment provider.", "properties": { "Message": { "type": "string", "description": "Provider operational message or error to be logged.", "nullable": true }, "tid": { "type": "string", "description": "Provider unique identifier for the transaction.", "nullable": true }, "authorizationId": { "type": "string", "description": "Provider authorization ID.", "nullable": true }, "status": { "type": "string", "description": "Order payment status in the [transaction flow](https://help.vtex.com/docs/tracks/the-transaction-flow).", "nullable": true }, "delayToAutoSettle": { "type": "integer", "description": "Total time (in seconds) before the auto settle, when the platform makes an automatic call to `/settlements`, regardless if the payment was approved by the merchant's anti-fraud provider. The maximum value allowed is `604800` seconds (7 days).", "nullable": true }, "ReturnCode": { "type": "string", "description": "Provider operational return code or error to be logged.", "nullable": true }, "nsu": { "type": "string", "description": "Provider unique sequential number for the transaction." }, "code": { "type": "string", "description": "Provider operational code or error to be logged." }, "message": { "type": "string", "description": "Provider operational message or error to be logged." }, "acquirer": { "type": "string", "description": "[Acquirer](https://help.vtex.com/docs/tracks/how-the-payments-module-works#acquirer) name (mostly used for card payments)." }, "authId": { "type": "string", "description": "Provider unique identifier for the transaction." }, "paymentId": { "type": "string", "description": "Payment ID." }, "delayToAutoSettleAfterAntifraud": { "type": "string", "description": "Total time (in seconds) before the auto settle, when the platform makes an automatic call to `/settlements`. This happens only after the payment was approved by the merchant's anti-fraud provider." } } } }, "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey" }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken" } }, "parameters": { "fulfillmentEndpoint": { "name": "fulfillmentEndpoint", "in": "path", "description": "This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.", "required": true, "style": "simple", "schema": { "type": "string", "example": "marketplaceexample.externalseller.com" } }, "Accept": { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, "Content-Type": { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, "content-length": { "name": "content-length", "in": "header", "description": "Length of the request body.", "required": true, "style": "simple", "schema": { "type": "string", "example": "2183" } }, "authorization": { "name": "authorization", "in": "header", "description": "Indicates authorization.", "required": true, "style": "simple", "schema": { "type": "string", "example": "VTEX key=\"appKey\" token=\"appToken\"" } }, "accept-enconding": { "name": "accept-enconding", "in": "header", "description": "Indicates the types of response enconding the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "gzip, deflate" } }, "vtexOperationID": { "name": "x-vtex-operation-id", "in": "header", "description": "VTEX operation ID.", "required": true, "style": "simple", "schema": { "type": "string", "example": "8032114b-63e9-4e64-b30c-f7afcf676d7a" } }, "forwardedProto": { "name": "x-forwarded-proto", "in": "header", "description": "Determines the protocol used by the client in the request.", "required": true, "style": "simple", "schema": { "type": "string", "example": "https" } }, "forwardedFor": { "name": "x-forwarded-for", "in": "header", "description": "Identifies the originating IP address of the HTTP client.", "required": true, "style": "simple", "schema": { "type": "string", "example": "179.35.30.186, 130.176.35.67, 172.16.247.49" } }, "vtexCacheClientBypass": { "name": "x-vtex-cache-client-bypass", "in": "header", "description": "VTEX cache client bypass.", "required": true, "style": "simple", "schema": { "type": "string", "example": "1" } }, "traceparent": { "name": "traceparent", "in": "header", "description": "Identifies the incoming request in a tracing system.", "required": true, "style": "simple", "schema": { "type": "string", "example": "00-083c0ca18bc8d94183f333809a70cd64-bf5e9a641e230540-00" } }, "sellerOrderId": { "name": "sellerOrderId", "in": "path", "description": "Seller's order ID of the order ready for fulfillment. The seller can be a VTEX seller or an external one.", "required": true, "example": "00-1268540501456-01", "style": "simple", "schema": { "type": "string", "example": "00-1268540501456-01" } }, "orderId": { "name": "orderId", "in": "path", "description": "ID of the order being fulfilled.", "required": true, "style": "simple", "schema": { "type": "string", "example": "1138342255777-01" } } } }, "tags": [ { "name": "External Seller" } ] }