{ "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://{accountName}.{environment}.com.br", "description": "VTEX Server URL.", "variables": { "accountName": { "description": "Name of the VTEX account. Used as part of the URL.", "default": "apiexamples" }, "environment": { "description": "Environment to use. Used as part of the URL.", "enum": [ "vtexcommercestable" ], "default": "vtexcommercestable" } } } ], "paths": { "/api/fulfillment/pvt/orders": { "post": { "tags": [ "External Marketplace" ], "summary": "Place fulfillment order", "description": "Creates fulfillment order, meaning that it is an order for the seller's side in a sale made through a marketplace. This order assumes the transaction itself has already happened on the marketplace's side and, therfore, cares only about the fulfillment side.\n\r\n\r> If you plan to integrate external orders with possible [Price divergence](https://help.vtex.com/en/tutorial/price-divergence-rule--6RlFLhD1rIRRshl83KnCjW#) be mindful of the `isCreatedAsync` request body field. \n\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/vtex-rest-api/docs/external-marketplace-integration-guide). \r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "PlaceFulfillmentOrder", "parameters": [ { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account. Used as part of the URL.", "schema": { "type": "string", "default": "apiexamples" } }, { "name": "environment", "in": "path", "required": true, "description": "Environment to be used. It is passed as part of the URL.", "schema": { "type": "string", "default": "vtexcommercestable" } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "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", "default": "application/json" } }, { "name": "sc", "in": "query", "description": "Sales channel.", "required": false, "style": "form", "schema": { "type": "string", "example": "1" } }, { "name": "affiliateId", "in": "query", "description": "ID identifying the marketplace where the order originates. This ID is configured in the seller's VTEX account, and should be informed to the marketplace.", "required": true, "style": "form", "schema": { "type": "string", "example": "MKP" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/placeFulfillmentOrderRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/placeFulfillmentOrderResponse" }, "example": { "orderId": "1234567890", "status": "success", "message": "Order placed successfully", "orderData": { "marketplaceOrderId": "123456789", "marketplaceServicesEndpoint": "https://exampleseller.marketplaceservices.com", "marketplacePaymentValue": 100, "isCreatedAsync": false, "items": [ { "id": "123456789", "quantity": 1, "seller": "1", "commission": 10, "freightCommission": 10, "price": 2499, "bundleItems": [], "itemAttachment": { "name": "name-example", "content": "content-example" }, "attachments": [], "priceTags": [], "measurementUnit": "g", "unitMultiplier": 1, "isGift": false } ], "clientProfileData": { "email": "customer@examplemail.com", "firstName": "first-name", "lastName": "last-name", "documentType": "cpf", "document": "123456789", "phone": "+55110988887777", "corporateName": "company-name", "tradeName": "trade-name", "corporateDocument": "12345678000100", "stateInscription": "12345678", "corporatePhone": "+551100988887777", "isCorporate": false }, "shippingData": { "address": { "addressType": "residential", "receiverName": "receiver-name", "addressId": "Home", "postalCode": "12345000", "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": [ "00.00000", "00.00000" ] }, "logisticsInfo": [ { "itemIndex": 0, "selectedSla": "Express", "lockTTL": "8d", "shippingEstimate": "7d", "price": 1099, "deliveryWindow": { "startDateUtc": "2023-01-01 00:00:00", "endDateUtc": "2023-01-02 00:00:00", "price": 0, "lisPrice": 0, "tax": 0 } } ], "updateStatus": "updated" }, "paymentData": "credit card", "marketingData": { "utmSource": "Facebook", "utmMedium": "CPC", "utmCampaign": "Black friday", "utmiPage": "utmi_page-example", "utmiPart": "utmi_part-example", "utmiCampaign": "utmi_campaign-example" }, "openTextField": "open-text-example" } } } } } }, "deprecated": false } }, "/api/fulfillment/pvt/orders/{orderId}/fulfill": { "post": { "tags": [ "External Marketplace" ], "summary": "Authorize dispatch for fulfillment order", "description": "Creates fulfillment order, meaning that it is an order for the seller's side in a sale made through a marketplace. This order assumes the transaction itself has already happened on the marketplace's side and, therfore, cares only about the fulfillment side. \n\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/vtex-rest-api/docs/external-marketplace-integration-guide).\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "AuthorizeDispatchForFulfillmentOrder", "parameters": [ { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account. Used as part of the URL.", "schema": { "type": "string", "default": "apiexamples" } }, { "name": "environment", "in": "path", "required": true, "description": "Environment to be used. It is passed as part of the URL.", "schema": { "type": "string", "default": "vtexcommercestable" } }, { "name": "orderId", "in": "path", "required": true, "description": "ID of the order that is to be authorized. It is composed of the `afilliateId` and the `marketplaceOrderId` joined with a `-`. For instance, an order with an ID `\"123\"` coming from the marketplace `\"MKP\"` has an `orderId` of `\"MKP-123\"`.", "schema": { "type": "string", "default": "MKP-123" } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "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", "default": "application/json" } }, { "name": "sc", "in": "query", "description": "Sales channel.", "required": false, "style": "form", "schema": { "type": "string", "example": "1" } }, { "name": "affiliateId", "in": "query", "description": "ID identifying the marketplace where the order originates. This ID is configured in the seller's VTEX account, and should be informed to the marketplace.", "required": true, "style": "form", "schema": { "type": "string", "example": "MKP" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "marketplaceOrderId": { "type": "string", "description": "ID of the order in the marketplace. It is the same as the `orderId` without the `afilliateId` at the beginning. For instance, if the `orderId` is `\"MKP-123\"`, the `marketplaceOrderId` is `\"123\"`.", "example": "123" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/orderIDFulfillmentResponse" }, "example": { "status": "success", "message": "Order created successfully", "orderId": "123", "details": { "createdAt": "2024-07-04T12:34:56Z", "marketplaceOrderId": "123", "status": "pending" } } } } } }, "deprecated": false } }, "/api/order-integration/orders": { "post": { "tags": [ "External Marketplace" ], "summary": "New Order Integration", "description": "API to integrate an external channel's order into the VTEX plataform.\n\nThis process is asynchronous and a notification with the order's integration results will be sent to the endpoint specified in the **connectorEndpoint** field in [App Template](https://developers.vtex.com/vtex-rest-api/docs/external-marketplace-integration-app-template), if the connector uses our App template. The field **connectorName** is also optional for connectors that use our App Template and authenticate using the app's auth cookie. If the account is not informed in the URL host, it should also be defined as a query string parameter in the route: `an={account}`. \n\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/vtex-rest-api/docs/external-marketplace-integration-guide).\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "EnqueueNewOrder", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "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", "default": "application/json" } }, { "name": "an", "in": "query", "description": "Parameter should indicate the name of the VTEX account where the order is being integrated or updated, meaning the seller responsible for the order.", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "apiexamples" } }, { "name": "accountName", "in": "path", "required": true, "description": "Parameter should indicate the name of the VTEX account where the order is being integrated or updated, meaning the seller responsible for the order.", "schema": { "type": "string", "default": "apiexamples" } }, { "name": "affiliateId", "in": "query", "description": "ID identifying the marketplace where the order originates. This ID is configured in the seller's VTEX account, and should be informed to the marketplace.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "MKP" } } ], "requestBody": { "description": "Request body containing data to enqueue a new order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnqueueNewOrderRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deliverybyseller" }, "example": { "marketplaceOrderId": null, "accountName": "grocery1", "code": "SOI003", "flow": "PlaceOrder", "success": true, "operationId": null, "errors": null, "fields": null, "message": "Order successfully enqueued" } } } }, "default": { "description": "Default response for successful order enqueue operation.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deliverybyfranchiseseller" }, "example": { "marketplaceOrderId": null, "accountName": "grocery1", "code": "SOI003", "flow": "PlaceOrder", "success": true, "operationId": null, "errors": null, "fields": null, "message": "Order successfully enqueued" } } } } }, "deprecated": false } }, "/api/order-integration/orders/status": { "put": { "tags": [ "External Marketplace" ], "summary": "Update Order Status", "description": "API request used to update an order status in VTEX.\n\nThis process is asynchronous and a notification with the order's integration results will be sent to the endpoint specified in the **connectiorEndpoint** field or the **connectiorEndpoint** [App Template](https://developers.vtex.com/vtex-rest-api/docs/external-marketplace-integration-app-template), if the connector uses our App template. The field **connectorName** is also optional for connectors that use our App Template and authenticate using the app's auth cookie. \n\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/vtex-rest-api/docs/external-marketplace-integration-guide).\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "UpdateOrderStatus", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Describes the type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "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", "default": "application/json" } }, { "name": "an", "in": "query", "description": "Parameter should indicate the name of the VTEX account where the order is being integrated or updated, meaning the seller responsible for the order.", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "apiexamples" } }, { "name": "accountName", "in": "path", "required": true, "description": "Parameter should indicate the name of the VTEX account where the order is being integrated or updated, meaning the seller responsible for the order.", "schema": { "type": "string", "default": "apiexamples" } } ], "requestBody": { "description": "Request body containing data to update the order status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderStatusRequest" }, "example": { "marketplaceOrderId": "{{$guid}}", "marketplaceOrderStatus": "approved", "connectorName": "Skyhub", "connectorEndpoint": "https://connector-endpoint.com/api/vtex" } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approveorder" }, "example": { "marketplaceOrderId": "7e62fcd3-827b-400d-be8a-f050a79c4976", "accountName": null, "code": "SOI003", "flow": "ApproveOrder", "success": true, "operationId": null, "errors": null, "fields": null, "message": "Order successfully enqueued" } } } } }, "deprecated": false } }, "/api/checkout/pub/orderForms/simulation": { "post": { "tags": [ "External Marketplace" ], "summary": "Fulfillment simulation - external marketplace", "description": "This endpoint can be triggered by marketplaces to simulate the fulfillment of an item in the cart.\r\n\r\nThe fulfillment information is useful whenever you need to know the availability of fulfilling an order for a specific cart setting, since the API response will let you know the updated price, inventory and shipping data.\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "fulfillment-simulation-external-marketplace", "parameters": [ { "name": "accountName", "in": "path", "required": true, "description": "Name of the VTEX account. Used as part of the URL.", "schema": { "type": "string", "default": "apiexamples" } }, { "name": "environment", "in": "path", "required": true, "description": "Environment to be used. It is passed as part of the URL.", "schema": { "type": "string", "default": "vtexcommercestable" } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "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", "default": "application/json" } }, { "name": "affiliateId", "in": "query", "description": "The affiliate ID code created by the seller.", "required": false, "style": "form", "schema": { "type": "string", "default": "MNF" } }, { "name": "sc", "in": "query", "description": "Trade Policy (Sales Channel) identification.", "required": false, "style": "form", "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "quantity", "seller" ], "description": "An object representing a single SKU inside the cart, detailing its ID, quantity, and the seller responsible.", "properties": { "items": { "type": "array", "description": "Array containing information about the SKUs inside the cart to be simulated.", "items": { "type": "object", "description": "Array containing information about the SKUs inside the cart to be simulated.", "properties": { "id": { "type": "string", "description": "The SKU ID.", "example": "1" }, "quantity": { "type": "integer", "format": "int32", "description": "The quantity of items of this specific SKU in the cart to be simulated.", "example": 1 }, "seller": { "type": "string", "description": "The ID of the seller responsible for this SKU. This ID can be found in your VTEX Admin.", "example": "1" } } } }, "marketingData": { "type": "object", "description": "Object containing promotion data such as coupon tracking information and internal or external UTMs.", "properties": { "coupon": { "type": "string", "description": "Sending an existing coupon code in this field will return the corresponding discount in the purchase. Use the [cart simulation](https://developers.vtex.com/vtex-rest-api/reference/orderform#orderformsimulation) request to check which coupons might apply before placing the order.", "example": "free-shipping" }, "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-example" }, "utmiCampaign": { "type": "string", "description": "utmi_campaign (internal utm).", "example": "utmi_campaign-example" } } }, "postalCode": { "type": "string", "description": "Postal code.", "example": "12345-000" }, "country": { "type": "string", "description": "Three letter ISO code of the country of the shipping address. This value must be sent along with the `postalCode` or `geoCoordinates` values.", "example": "BRA" }, "selectedSla": { "type": "string", "description": "SLA selected by the customer.", "example": "Normal" }, "clientProfileData": { "type": "object", "description": "Customer's profile information.", "properties": { "email": { "type": "string", "description": "Email address.", "example": "clark.kent@example.com" }, "firstName": { "type": "string", "description": "First name.", "example": "Clark" }, "lastName": { "type": "string", "description": "Last name.", "example": "Kent" }, "documentType": { "type": "string", "description": "Type of the document informed by the customer.", "example": "cpf" }, "document": { "type": "string", "description": "Document informed by the customer.", "example": "12345678900" }, "phone": { "type": "string", "description": "Phone number.", "example": "+552199999999" }, "corporateName": { "type": "string", "description": "Company name, if the customer is a legal entity.", "nullable": true, "example": "companyName" }, "tradeName": { "type": "string", "description": "Trade name, if the customer is a legal entity.", "nullable": true, "example": "tradeName" }, "corporateDocument": { "type": "string", "description": "Corporate document, if the customer is a legal entity.", "nullable": true, "example": "corporateDocument" }, "stateInscription": { "type": "string", "description": "State inscription, if the customer is a legal entity.", "nullable": true, "example": "stateInscription" }, "corporatePhone": { "type": "string", "description": "Corporate phone number, if the customer is a legal entity.", "nullable": true, "example": "corporatePhone" }, "isCorporate": { "type": "boolean", "description": "Indicates whether the customer is a legal entity.", "example": true }, "profileCompleteOnLoading": { "type": "boolean", "description": "Indicates whether profile is complete on loading.", "example": false }, "profileErrorOnLoading": { "type": "boolean", "description": "Indicates whether profile presents error on loading.", "nullable": true, "example": false }, "customerClass": { "type": "string", "description": "Customer class.", "nullable": true, "example": "customerClass" } } }, "geoCoordinates": { "type": "array", "description": "Array containing two floats with geocoordinates, first longitude, then latitude.", "example": [ -47.924747467041016, -15.832582473754883 ], "items": { "type": "number", "description": "A float representing either longitude or latitude coordinate.", "example": -47.924747467041016 } }, "isCheckedIn": { "type": "boolean", "description": "Indicates whether order is checked in.", "default": false }, "storeId": { "type": "string", "description": "ID of the store.", "nullable": true } } } } } }, "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "Information on each item in the cart.", "items": { "type": "object", "description": "Detailed information about a specific item in the cart, including its attributes such as ID, name, price, and quantity.", "properties": { "id": { "type": "string", "description": "ID of the item." }, "requestIndex": { "type": "integer", "description": "Request index information." }, "quantity": { "type": "integer", "description": "The quantity of the item the cart." }, "seller": { "type": "string", "description": "The seller responsible for the SKU." }, "sellerChain": { "type": "array", "description": "Sellers involved in the chain. The list should contain only one seller, unless it is a [Multilevel Omnichannel Inventory](https://help.vtex.com/en/tutorial/multilevel-omnichannel-inventory--7M1xyCZWUyCB7PcjNtOyw4) order.", "items": { "type": "string", "description": "Seller." } }, "tax": { "type": "integer", "description": "Tax value in cents." }, "priceValidUntil": { "type": "string", "description": "Price expiration date and time." }, "price": { "type": "integer", "description": "Price in cents." }, "listPrice": { "type": "integer", "description": "List price in cents." }, "rewardValue": { "type": "integer", "description": "Reward value in cents." }, "sellingPrice": { "type": "integer", "description": "Selling price in cents. Note that this field may be subject to rounding discrepancies. We recommend retrieving data from the `priceDefinition` data structure instead." }, "offerings": { "type": "array", "description": "Array containing offering information.", "items": { "type": "object", "description": "Details of offering information.", "properties": { "id": { "type": "string", "description": "Identifier of the offering." }, "name": { "type": "string", "description": "Name of the offering." }, "price": { "type": "integer", "description": "Price of the offering in cents." }, "availability": { "type": "string", "description": "Availability status of the offering." } } } }, "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": { "type": "object", "description": "Details of a price tag.", "properties": { "name": { "type": "string", "description": "Price tag name." }, "value": { "type": "integer", "description": "Price tag value." }, "rawValue": { "type": "integer", "description": "Price tag raw value." }, "isPercentual": { "type": "boolean", "description": "Indicates whether price tag value is applied through a percentage." }, "identifier": { "type": "string", "description": "Price tag identifier." }, "owner": { "type": "string", "description": "Identification of the responsible for the price tag." } } } }, "measurementUnit": { "type": "string", "description": "Measurement unit." }, "unitMultiplier": { "type": "integer", "description": "Unit multiplier." }, "parentItemIndex": { "type": "integer", "description": "Parent item index.", "nullable": true }, "parentAssemblyBinding": { "type": "string", "description": "Parent assembly binding.", "nullable": true }, "availability": { "type": "string", "description": "Availability." }, "priceDefinition": { "type": "object", "description": "Price information for all units of a specific item.", "properties": { "calculatedSellingPrice": { "type": "integer", "description": "Item's calculated unitary selling price in cents." }, "total": { "type": "integer", "description": "Total value for all units of the item in cents." }, "sellingPrices": { "type": "array", "description": "Array of objects, each containing value (in cents) and quantity for the different rounding instances that can be combined to form the correctly rounded total.", "items": { "type": "object", "description": "Details of a selling price instance.", "properties": { "value": { "type": "integer", "description": "Value in cents for that specific rounding." }, "quantity": { "type": "integer", "description": "Rounding quantity, meaning how many items are rounded to this value." } } } } } } } } }, "ratesAndBenefitsData": { "type": "object", "description": "Information on rates and benefits that apply to the order.", "properties": { "rateAndBenefitsIdentifiers": { "type": "array", "description": "List with rates and benefits identifiers.", "items": { "type": "object", "description": "Details of a rate and benefits identifier.", "properties": { "id": { "type": "string", "description": "Identifier of the rate or benefit." }, "name": { "type": "string", "description": "Name of the rate or benefit." } } } }, "teaser": { "type": "array", "description": "List with rates and benefits teasers.", "items": { "type": "object", "description": "Details of a teaser containing rates and benefits.", "properties": { "name": { "type": "string", "description": "Teaser name." }, "description": { "type": "string", "description": "Teaser description." } } } } } }, "paymentData": { "type": "object", "description": "Payment data information.", "properties": { "installmentOptions": { "type": "array", "description": "Installment options information.", "items": { "type": "array", "description": "Array containing installment options available for payment.", "items": { "type": "object", "description": "Details of payment options.", "properties": { "paymentSystem": { "type": "integer", "description": "Payment system identification." }, "bin": { "type": "string", "description": "Bin.", "nullable": true }, "paymentName": { "type": "string", "description": "Payment name." }, "paymentGroupName": { "type": "string", "description": "Payment group name." }, "value": { "type": "integer", "description": "Total value assigned to this payment." }, "installments": { "type": "array", "description": "Installments information.", "items": { "type": "object", "description": "Details of each installment payment.", "properties": { "count": { "type": "integer", "description": "Count information." }, "hasInterestRate": { "type": "boolean", "description": "Indicates whether the payment has interest." }, "interestRate": { "type": "integer", "description": "Interest rate value." }, "value": { "type": "integer", "description": "Value of the order without the interest rate. The value is shown without separating cents." }, "total": { "type": "integer", "description": "Total value of the order without separating cents. For example, $24.99 is represented `2499`." }, "sellerMerchantInstallments": { "type": "array", "description": "Seller merchant installments information.", "items": { "type": "object", "description": "Details of seller merchant installments.", "properties": { "id": { "type": "integer", "description": "Seller ID." }, "count": { "type": "integer", "description": "Installment count." }, "value": { "type": "integer", "description": "Installment value." } } } } } } } } } } }, "paymentSystems": { "type": "array", "description": "Information on payment systems.", "items": { "type": "object", "description": "Details of a payment system.", "properties": { "id": { "type": "integer", "description": "Payment system ID." }, "name": { "type": "string", "description": "Payment system name." }, "groupName": { "type": "string", "description": "Payment group name." }, "validator": { "type": "object", "description": "Payment system validator.", "nullable": true }, "stringId": { "type": "string", "description": "String ID." }, "template": { "type": "string", "description": "Template." }, "requiresDocument": { "type": "boolean", "description": "Indicates whether a document is required." }, "displayDocument": { "type": "boolean", "description": "Indicates whether a document is shown." }, "isCustom": { "type": "boolean", "description": "Indicates whether it is custom." }, "selectableGifts": { "type": "array", "description": "Array containing the data of the item selected as a gift.", "items": { "type": "object", "description": "Details of the item selected as a gift.", "properties": { "giftItemId": { "type": "string", "description": "Identifier of the gift item." }, "giftItemName": { "type": "string", "description": "Name of the gift item." }, "giftItemDescription": { "type": "string", "description": "Description of the gift item." }, "giftItemPrice": { "type": "number", "description": "Price of the gift item." } } } }, "marketingData": { "type": "object", "description": "Object containing promotion data such as coupon tracking information and internal or external UTMs.", "nullable": true }, "postalCode": { "type": "string", "description": "Postal Code.", "nullable": true }, "country": { "type": "string", "description": "Three letter ISO code of the country of the shipping address." }, "logisticsInfo": { "type": "array", "description": "Array with logistics information on each item of the `items` array in the `orderForm`.", "items": { "description": "Logistics information for an item.", "type": "object", "properties": { "itemIndex": { "type": "integer", "description": "Index of item in items array." }, "addressId": { "type": "string", "description": "Address ID.", "nullable": true }, "selectedSla": { "type": "string", "description": "Selected SLA. For example, `\"normal\"` or `\"express\"`.", "nullable": true }, "selectedDeliveryChannel": { "type": "string", "description": "Delivery channel selected by the customer. For example, `\"delivery\"` or `\"pickup-in-point\"`.", "nullable": true }, "quantity": { "type": "integer", "description": "Indicates the number of items in the order." }, "shipsTo": { "type": "array", "description": "List of countries that the item may be shipped to.", "items": { "type": "string", "description": "Country code indicating where the item may be shipped." } }, "slas": { "type": "array", "description": "Information on available SLAs.", "items": { "type": "object", "description": "Service Level Agreements (SLAs) available for the order.", "properties": { "id": { "type": "string", "description": "SLA ID." }, "deliveryChannel": { "type": "string", "description": "Delivery channel." }, "name": { "type": "string", "description": "SLA name." }, "deliveryIds": { "type": "array", "description": "Information on each delivery ID.", "items": { "type": "object", "description": "Details on each delivery ID.", "properties": { "courierId": { "type": "string", "description": "Courier ID." }, "warehouseId": { "type": "string", "description": "Warehouse ID." }, "dockId": { "type": "string", "description": "Warehouse ID." }, "courierName": { "type": "string", "description": "Courier name." }, "quantity": { "type": "integer", "description": "Quantity." } } } }, "shippingEstimate": { "type": "string", "description": "Shipping estimate. For instance, \"three business days\" will be represented as `3bd`." }, "shippingEstimateDate": { "type": "string", "description": "Shipping estimate date.", "nullable": true }, "lockTTL": { "type": "string", "description": "Estimate date of delivery." }, "availableDeliveryWindows": { "type": "object", "description": "This object contains information about the delivery window available to the shopper.", "properties": { "startDateUtc": { "type": "string", "description": "Delivery window starting day and time in UTC." }, "endDateUtc": { "type": "string", "description": "Delivery window ending day and time in UTC." }, "price": { "type": "integer", "description": "Delivery window price." }, "lisPrice": { "type": "integer", "description": "Delivery window list price." }, "tax": { "type": "integer", "description": "Delivery window tax." } } }, "deliveryWindow": { "type": "object", "description": "In case of scheduled delivery, this object will contain information on the delivery window selected by the shopper.", "properties": { "startDateUtc": { "type": "string", "description": "Delivery window starting day and time in UTC." }, "endDateUtc": { "type": "string", "description": "Delivery window ending day and time in UTC." }, "price": { "type": "integer", "description": "Delivery window price." }, "lisPrice": { "type": "integer", "description": "Delivery window list price." }, "tax": { "type": "integer", "description": "Delivery window tax." } } }, "price": { "type": "integer", "description": "Price in cents." }, "listPrice": { "type": "integer", "description": "List price in cents." }, "tax": { "type": "integer", "description": "Tax in cents." }, "pickupStoreInfo": { "type": "object", "description": "Information on the pickup store.", "properties": { "isPickupStore": { "type": "boolean", "description": "Indicates whether it is the pickup store." }, "friendlyName": { "type": "string", "description": "Friendly name.", "nullable": true }, "address": { "type": "object", "description": "Address information.", "nullable": true }, "additionalInfo": { "type": "string", "description": "Additional information.", "nullable": true }, "dockId": { "type": "string", "description": "Corresponding dock ID.", "nullable": true } } }, "pickupPointId": { "type": "string", "description": "Pickup point ID.", "nullable": true }, "pickupDistance": { "type": "integer", "description": "Pickup point distance." }, "polygonName": { "type": "string", "description": "Polygon name.", "nullable": true }, "transitTime": { "type": "string", "description": "Transit time. For instance, \"three business days\" is represented as `3bd`." } } } }, "deliveryChannels": { "type": "array", "description": "List of available delivery channels.", "items": { "type": "object", "description": "Information about a specific delivery channel.", "properties": { "id": { "type": "string", "description": "Delivery channel ID." } } } }, "messages": { "type": "array", "description": "Array containing an object for each message generated by our servers while processing the request.", "items": { "type": "object", "description": "Details of a message generated during server processing.", "properties": { "messageId": { "type": "string", "description": "Identifier of the message." }, "messageText": { "type": "string", "description": "Content of the message." }, "messageType": { "type": "string", "description": "Type of the message (e.g., error, warning, info)." } } } }, "purchaseConditions": { "type": "object", "description": "Purchase conditions information.", "properties": { "itemPurchaseConditions": { "type": "array", "description": "List of objects containing purchase condition information on each item in the order.", "items": { "type": "object", "description": "Object containing purchase condition information on each item in the order.", "properties": { "id": { "type": "string", "description": "Item ID." }, "seller": { "type": "string", "description": "Seller." }, "sellerChain": { "type": "array", "description": "Sellers involved in the chain. The list should contain only one seller, unless it is a [Multilevel Omnichannel Inventory](https://help.vtex.com/en/tutorial/multilevel-omnichannel-inventory--7M1xyCZWUyCB7PcjNtOyw4) order.", "items": { "type": "object", "description": "Details of each seller involved in the chain.", "properties": { "sellerId": { "type": "string", "description": "Identifier of the seller." }, "sellerName": { "type": "string", "description": "Name of the seller." }, "sellerLocation": { "type": "string", "description": "Location or address of the seller." } } } }, "slas": { "type": "array", "description": "Information on available SLAs.", "items": { "type": "object", "description": "Object containing details of a Service Level Agreement (SLA).", "properties": { "id": { "type": "string", "description": "SLA ID." }, "deliveryChannel": { "type": "string", "description": "Delivery channel." }, "name": { "type": "string", "description": "SLA name." }, "deliveryIds": { "type": "array", "description": "Information on each delivery ID.", "items": { "type": "object", "description": "Detailed information about each item in the order.", "properties": { "courierId": { "type": "string", "description": "Courier ID." }, "warehouseId": { "type": "string", "description": "Warehouse ID." }, "dockId": { "type": "string", "description": "Dock ID." }, "courierName": { "type": "string", "description": "Courier name." }, "quantity": { "type": "integer", "description": "Quantity." } } } }, "shippingEstimate": { "type": "string", "description": "Shipping estimate. For instance, \"three business days\" will be represented as `3bd`." }, "shippingEstimateDate": { "type": "string", "description": "Shipping estimate date.", "nullable": true }, "lockTTL": { "type": "string", "description": "Estimate date of delivery." }, "availableDeliveryWindows": { "type": "object", "description": "This object contains information about the delivery window available to the shopper.", "properties": { "startDateUtc": { "type": "string", "description": "Delivery window starting day and time in UTC." }, "endDateUtc": { "type": "string", "description": "Delivery window ending day and time in UTC." }, "price": { "type": "integer", "description": "Delivery window price." }, "lisPrice": { "type": "integer", "description": "Delivery window list price." }, "tax": { "type": "integer", "description": "Delivery window tax." } } }, "deliveryWindow": { "type": "object", "description": "In case of scheduled delivery, this object will contain information on the delivery window selected by the shopper.", "properties": { "startDateUtc": { "type": "string", "description": "Delivery window starting day and time in UTC." }, "endDateUtc": { "type": "string", "description": "Delivery window ending day and time in UTC." }, "price": { "type": "integer", "description": "Delivery window price." }, "lisPrice": { "type": "integer", "description": "Delivery window list price." }, "tax": { "type": "integer", "description": "Delivery window tax." } } }, "price": { "type": "integer", "description": "Price in cents." }, "listPrice": { "type": "integer", "description": "List price in cents." }, "tax": { "type": "integer", "description": "Tax in cents." }, "pickupStoreInfo": { "type": "object", "description": "Information on the pickup store.", "properties": { "isPickupStore": { "type": "boolean", "description": "Indicates whether it is the pickup store." }, "friendlyName": { "type": "string", "description": "Friendly name.", "nullable": true }, "address": { "type": "object", "description": "Address information.", "nullable": true }, "additionalInfo": { "type": "string", "description": "Additional information.", "nullable": true }, "dockId": { "type": "string", "description": "Corresponding dock ID.", "nullable": true } } }, "pickupPointId": { "type": "string", "description": "Pickup point ID.", "nullable": true }, "pickupDistance": { "type": "integer", "description": "Pickup point distance." }, "polygonName": { "type": "string", "description": "Polygon name.", "nullable": true }, "transitTime": { "type": "string", "description": "Transit time. For instance, \"three business days\" is represented as `3bd`." } } } }, "price": { "type": "integer", "description": "Price in cents." }, "listPrice": { "type": "integer", "description": "List price in cents." } } } } } }, "pickupPoints": { "type": "array", "description": "Array containing pickup points information.", "items": { "description": "Details of a pickup point.", "type": "object", "properties": { "pickupPointId": { "type": "string", "description": "Pickup point ID." }, "friendlyName": { "type": "string", "description": "Friendly name of the pickup point.", "nullable": true }, "address": { "type": "object", "description": "Address information of the pickup point.", "nullable": true, "properties": { "street": { "type": "string", "description": "Street address." }, "number": { "type": "string", "description": "Street number." }, "neighborhood": { "type": "string", "description": "Neighborhood." }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal code." } } }, "additionalInfo": { "type": "string", "description": "Additional information about the pickup point.", "nullable": true }, "dockId": { "type": "string", "description": "Dock ID of the pickup point.", "nullable": true } } } }, "subscriptionData": { "type": "object", "description": "Subscription information.", "nullable": true }, "totals": { "type": "array", "description": "Information on order totals.", "items": { "type": "object", "description": "Object containing information about a specific total in the order.", "properties": { "id": { "type": "string", "description": "Total ID." }, "name": { "type": "string", "description": "Total name." }, "value": { "type": "integer", "description": "Total value." } } } }, "itemMetadata": { "type": "object", "description": "Item metadata.", "properties": { "items": { "type": "array", "description": "List of objects containing metadata on each item in the order.", "items": { "type": "object", "description": "Detailed information about each item in the order.", "properties": { "id": { "type": "string", "description": "Item ID." }, "seller": { "type": "string", "description": "Seller." }, "assemblyOptions": { "type": "array", "description": "Assembly options information.", "items": { "description": "Details of an assembly option.", "type": "object", "properties": { "id": { "type": "string", "description": "Item ID." }, "name": { "type": "string", "description": "Item name." }, "required": { "type": "boolean", "description": "Indicates whether the item is required." }, "inputValues": { "type": "object", "description": "Input values information." }, "composition": { "type": "string", "description": "Composition information.", "nullable": true } } } } } } } } } } } } } } } } } }, "deprecated": false }, "example": { "items": [ { "id": "1", "requestIndex": 0, "quantity": 1, "seller": "1", "sellerChain": [ "1" ], "tax": 0, "priceValidUntil": "2023-07-12T11:49:01Z", "price": 9999, "listPrice": 9999, "rewardValue": 0, "sellingPrice": 2999700, "offerings": [ { "id": "14", "name": "offeringExample", "price": 15099, "availability": "available" } ], "priceTags": [ { "name": "DISCOUNT@MANUALPRICE", "value": -5000, "rawValue": -50.0, "isPercentual": false, "identifier": "1234abc-5678b-1234c", "owner": "ownerExample" } ], "measurementUnit": "un", "unitMultiplier": 300.0000, "parentItemIndex": null, "parentAssemblyBinding": null, "availability": "available", "priceDefinition": { "calculatedSellingPrice": 2999700, "total": 2999700, "sellingPrices": [ { "value": 2999700, "quantity": 1 } ] } } ], "ratesAndBenefitsData": { "rateAndBenefitsIdentifiers": [ { "id": "245", "name": "giftcard" } ], "teaser": [ { "name": "teaserName", "description":"descriptionTeaser" } ] }, "paymentData": { "installmentOptions": [ [ { "paymentSystem": 123, "bin": "123456", "paymentName": "Credit Card", "paymentGroupName": "Credit Cards", "value": 100000, "installments": [ { "count": 1, "hasInterestRate": false, "interestRate": 0, "value": 100000, "total": 100000, "sellerMerchantInstallments": [ { "id": 1, "count": 1, "value": 100000 } ] }, { "count": 3, "hasInterestRate": true, "interestRate": 5, "value": 34000, "total": 102000, "sellerMerchantInstallments": [ { "id": 1, "count": 3, "value": 34000 } ] } ] } ], [ { "paymentSystem": 456, "bin": null, "paymentName": "PayPal", "paymentGroupName": "Digital Wallets", "value": 100000, "installments": [ { "count": 1, "hasInterestRate": false, "interestRate": 0, "value": 100000, "total": 100000, "sellerMerchantInstallments": [ { "id": 2, "count": 1, "value": 100000 } ] } ] } ] ] }, "selectableGifts": [], "marketingData": { "utmSource": "app", "utmMedium": "CPC", "utmCampaign": "Black friday", "utmipage": "true", "utmiPart": "true", "utmiCampaign": "true", "coupon": null, "marketingTags": [ "tag1", "tag2" ] }, "country": "BRA", "postalCode": "12345-000", "geoCoordinates": [ -47.924747467041016, -15.832582473754883 ], "logisticsInfo": [ { "itemIndex": 0, "addressId": null, "selectedSla": null, "selectedDeliveryChannel": null, "quantity": 1, "shipsTo": [ "BRA" ], "slas": [ { "id": "Normal", "deliveryChannel": "delivery", "name": "Normal", "deliveryIds": [ { "courierId": "1", "warehouseId": "1_1", "dockId": "1", "courierName": "Transportadora", "quantity": 1, "kitItemDetails": [] } ], "shippingEstimate": "3bd", "shippingEstimateDate": null, "lockTTL": "10d", "availableDeliveryWindows": { "startDateUtc": "2017-03-27T00:00:00+00:00", "endDateUtc": "2017-03-27T00:00:00+00:00", "price": 0, "lisPrice": 0, "tax": 0 }, "deliveryWindow": { "startDateUtc": "2014-04-21T09:00:00+00:00", "endDateUtc": "2014-04-21T12:00:00+00:00", "price": 0, "listprice": 1000, "tax": 0 }, "price": 1500, "listPrice": 1500, "tax": 0, "pickupStoreInfo": { "isPickupStore": false, "friendlyName": null, "address": null, "additionalInfo": null, "dockId": null }, "pickupPointId": null, "pickupDistance": 0, "polygonName": null, "transitTime": "3bd" } ], "deliveryChannels": [ { "id": "pickup-in-point" }, { "id": "delivery" } ] } ], "messages": [], "purchaseConditions": { "itemPurchaseConditions": [ { "id": "1", "seller": "1", "sellerChain": [ "1" ], "slas": [ { "id": "Normal", "deliveryChannel": "delivery", "name": "Normal", "deliveryIds": [ { "courierId": "1", "warehouseId": "1_1", "dockId": "1", "courierName": "Transportadora", "quantity": 1, "kitItemDetails": [] } ], "shippingEstimate": "3bd", "shippingEstimateDate": null, "lockTTL": "10d", "availableDeliveryWindows": { "startDateUtc": "2017-03-27T00:00:00+00:00", "endDateUtc": "2017-03-27T00:00:00+00:00", "price": 0, "lisPrice": 0, "tax": 0 }, "deliveryWindow": { "startDateUtc": "2014-04-21T09:00:00+00:00", "endDateUtc": "2014-04-21T12:00:00+00:00", "price": 0, "listprice": 1000, "tax": 0 }, "price": 1500, "listPrice": 1500, "tax": 0, "pickupStoreInfo": { "isPickupStore": false, "friendlyName": null, "address": null, "additionalInfo": null, "dockId": null }, "pickupPointId": null, "pickupDistance": 0, "polygonName": null, "transitTime": "3bd" } ], "price": 9999, "listPrice": 9999 } ] }, "pickupPoints": [], "subscriptionData": null, "totals": [ { "id": "Items", "name": "Total dos Itens", "value": 2999700 } ], "itemMetadata": { "items": [ { "id": "1", "seller": "1", "assemblyOptions": [ { "id": "T-Shirt Customization", "name": "T-Shirt Customization", "required": false, "inputValues": { "T-Shirt Name": { "maximumNumberOfCharacters": 2, "domain": [ "[]" ] } }, "composition": null } ] } ] } } } } } } } } }, "security": [ { "appKey": [], "appToken": [] } ], "components": { "schemas": { "EnqueueNewOrderRequest": { "required": [ "marketplaceOrderId", "marketplaceOrderStatus", "marketplacePaymentValue", "allowFranchises", "items", "clientProfileData", "shippingData", "invoiceData" ], "type": "object", "description": "Object for enqueueing a new order.", "properties": { "marketplaceOrderId": { "type": "string", "description": "String that indicates the order's ID in the marketplace." }, "connectorName": { "type": "string", "description": "String with the identifier code of the connector responsible for the order. This field is optional if the connector uses the App Template and authenticates via `VtexIdclientAutCookie`." }, "connectorEndpoint": { "type": "string", "description": "String with the connector's base endpoint that will receive notifications about the order's processing results and status updates from VTEX OMS." }, "marketplaceOrderStatus": { "type": "string", "description": "Order's status in the marketplace. Accepts the values: `new` and `approved`." }, "marketplacePaymentValue": { "type": "integer", "description": "Integer that indicates the order's total value, which the marketplace will pay to the seller. Includes interest, if applicable. If the value is `USD110.50`, convert it to `11050`." }, "marketplaceInterestValue": { "type": "integer", "description": "Integer with the interest amount included in the order's total value. If the value is `USD10.50`, convert it to `1050`." }, "priceDivergenceAllowanceRate": { "type": "number", "format": "double", "description": "Decimal value with the allowed price divergence rate between the marketplace and the seller's prices." }, "allowFranchises": { "type": "boolean", "description": "Boolean indicating whether franchise accounts linked to the main seller should be considered. Optional, defaulting to `false`." }, "pickupAccountName": { "type": "string", "description": "String that indicates the name of the account responsible for the order's pickup point. Required only for pickup-in-point orders from franchise accounts." }, "items": { "type": "array", "description": "List of items included in the order.", "items": { "$ref": "#/components/schemas/Item" } }, "clientProfileData": { "$ref": "#/components/schemas/ClientProfileData" }, "shippingData": { "$ref": "#/components/schemas/ShippingData" }, "invoiceData": { "$ref": "#/components/schemas/InvoiceData" }, "customData": { "$ref": "#/components/schemas/CustomData" }, "taxData": { "type": "array", "description": "List of tax information per SKU in the order.", "items": { "$ref": "#/components/schemas/TaxData" } }, "openTextField": { "type": "string", "description": "String with additional free-text information about the order." } }, "example": { "marketplaceOrderId": "123", "connectorName": "SkyHub", "connectorEndpoint": "https://connector-endpoint.com/api/vtex", "marketplaceOrderStatus": "new", "marketplacePaymentValue": 3025, "marketplaceInterestValue": 0, "priceDivergenceAllowanceRate": 0.05, "allowFranchises": false, "pickupAccountName": "testAccount", "items": [ { "id": "1", "price": 975, "quantity": 1 } ], "clientProfileData": { "email": "email@email.com.br", "firstName": "John", "lastName": "Doe", "phone": "99999999999", "document": "99999999999", "corporateDocument": null, "corporatePhone": null, "corporateName": null, "tradeName": null, "stateInscription": null }, "shippingData": { "logisticsInfo": [ { "price": 2050, "selectedDeliveryChannel": "delivery", "selectedSla": "Express", "lockTTL": "1d", "shippingEstimate": "2d", "deliveryIds": [ { "warehouseId": "AR1" } ] } ], "selectedAddresses": [ { "addressType": "Residential", "addressId": "1", "receiverName": "John Doe", "postalCode": "81020-235", "city": "Curitiba", "state": "PR", "country": "BRA", "street": "Rua Eduardo Carlos Pereira", "number": "4125", "neighborhood": "Portão", "complement": "101", "geoCoordinates": { "latitude": -29.5, "longitude": -45.8 } } ], "isFob": true, "isMarketplaceFulfillment": true, "trackingHints": [ { "trackingId": "BR123456789", "courierName": "Correios", "trackingUrl": "https://tracking.example.com/BR123456789", "trackingLabel": "Correios Express" } ] }, "invoiceData": { "userPaymentInfo": { "paymentMethods": [ "creditCardPaymentGroup" ] } }, "customData": { "customApps": [ { "id": "marketplace-integration", "major": 1, "fields": { "marketplacePaymentMethod": "credit card" } } ] }, "taxData": [ { "skuId": "1", "value": 150 } ], "openTextField": "Additional order information." } }, "Item": { "required": [ "id", "price", "quantity" ], "type": "object", "description": "Object containing information about an item in the order.", "properties": { "id": { "type": "string", "description": "String with the SKU ID in VTEX’s catalog.", "example": "1" }, "price": { "type": "integer", "description": "Integer with the SKU’s unit price. If the value is `USD110.50`, convert it to the format → `11050`.", "example": 11050 }, "quantity": { "type": "integer", "description": "Integer with the quantity of the SKU present in the order. The value should be greater than zero.", "example": 10 } }, "example": { "id": "1", "price": 975, "quantity": 1 } }, "ClientProfileData": { "description": "Structure with the customer's information. An order will be identified as corporate if any of the corporate fields are filled out (`corporateDocument`, `corporatePhone`, `corporateName` or `tradeName`).", "required": [ "email", "firstName", "lastName", "phone", "document", "corporateDocument", "corporatePhone", "corporateName", "tradeName", "stateInscription" ], "type": "object", "properties": { "email": { "type": "string", "description": "String with the customer's email.", "example": "cirilla@cintra.com" }, "firstName": { "type": "string", "description": "String with the customer's first name.", "example": "Cirilla" }, "lastName": { "type": "string", "description": "String with the customer’s surname.", "example": "Cintra" }, "phone": { "type": "string", "description": "String with the customer’s phone number.", "example": "99999999999" }, "document": { "type": "string", "description": "String with the customer’s document number.", "example": "99999999999" }, "corporateDocument": { "type": "string", "description": "String with the company’s document number, in case of corporate orders.", "nullable": true, "example": "99999999999" }, "corporatePhone": { "type": "string", "description": "String with the company’s phone number, in case of corporate orders.", "nullable": true, "example": "99999999999" }, "corporateName": { "type": "string", "description": "String with the company’s name, in case of corporate orders.", "nullable": true, "example": "The Witcher Inc." }, "tradeName": { "type": "string", "description": "String with the company’s fantasy name, in case of corporate orders.", "nullable": true, "example": "The Witcher" }, "stateInscription": { "type": "string", "description": "String with the company’s state registration, in case of corporate orders.", "nullable": true, "example": "99999999999" } } }, "ShippingData": { "required": [ "logisticsInfo", "selectedAddresses", "isFob", "isMarketplaceFulfillment" ], "type": "object", "description": "Object containing shipping information for the order.", "properties": { "logisticsInfo": { "type": "array", "description": "List that references the SLAs responsible for delivering each item in the order.", "items": { "$ref": "#/components/schemas/LogisticsInfo" } }, "selectedAddresses": { "type": "array", "description": "List of selected addresses for the order.", "items": { "$ref": "#/components/schemas/SelectedAddress" } }, "isFob": { "type": "boolean", "description": "Boolean that indicates whether the order's delivery is the marketplace responsibility. Optional, defaulting to `false`." }, "isMarketplaceFulfillment": { "type": "boolean", "description": "Boolean that indicates whether the order's inventory in warehouse is the marketplace's responsibility. Optional, defaulting to `false`." }, "trackingHints": { "type": "array", "description": "List of tracking information hints for the order's shipments.", "items": { "$ref": "#/components/schemas/TrackingHint" } } } }, "LogisticsInfo": { "description": "List that references the SLAs responsible for delivering each item in the order. \n\nThis list must contain the same number of items as the `items` list, previously defined. For example: if the order contains 3 SKUs, you must describe 3 SLAs in this list, one for each SKU (even in cases where the same SLA will deliver all of them). \n\nThe order of the SLAs in this list must also follow the same order as in the `items` list. For example: if the SLA named **Correios Express** will be responsible for delivering the SKU with ID equal to **1015**, which is found at index 0 of the `items` list, it must be in index 0 of the `logisticsInfo` list as well.", "required": [ "price", "selectedDeliveryChannel", "selectedSla", "lockTTL", "shippingEstimate", "deliveryIds" ], "type": "object", "properties": { "price": { "type": "integer", "description": "Integer indicating the shipping price for this SKU. If the value is `USD20.50`, convert it to the format → `2050`.", "example": 2050 }, "selectedDeliveryChannel": { "type": "string", "description": "String with the selected delivery channel. This field supports the following values: \n\n- `delivery`, \n\n- `pickup-in-point`.", "example": "delivery" }, "selectedSla": { "type": "string", "description": "String with the selected delivery SLA.", "example": "T-G1-2-Express" }, "lockTTL": { "type": "string", "description": "String with the inventory reservation period in VTEX's logistics system. To fill in this field insert the number of days, followed by the letter for the chosen unit. \n\n- Days: `d` \n\n- Business days: `bd`. \n\nExample formats: `12d`, `5d`.", "example": "5d" }, "shippingEstimate": { "type": "string", "description": "String with the order's estimated delivery time. To fill in this field, insert a number, followed by the letter for the chosen unit. \n\n- Days: `d` \n\n- Business days: `bd`. \n\n- Hours: `h` \n\n- Minutes: `m`. \n\nExample formats: `12d`, `5bd`, `3h`, `50m`.", "example": "7d" }, "deliveryIds": { "type": "array", "description": "List of delivery IDs, used for orders where the marketplace is responsible for the fulfillment of the order.", "items": { "$ref": "#/components/schemas/DeliveryIds" } } }, "example": { "price": 2050, "selectedDeliveryChannel": "delivery", "selectedSla": "Express", "lockTTL": "1d", "shippingEstimate": "2d", "deliveryIds": [ { "warehouseId": "AR1" } ] } }, "DeliveryIds": { "description": "Object with the delivery ID information for orders where the marketplace is responsible for the fulfillment of the order, including keeping inventory at a warehouse as well as the delivery.", "required": [ "warehouseId" ], "type": "object", "properties": { "warehouseId": { "type": "string", "description": "String with the ID of the warehouse used for marketplace fulfillment. Required when `isFob` = `true` and `isMarketplaceFulfillment` = `true`.", "example": "AR1" } }, "example": { "warehouseId": "AR1" } }, "SelectedAddress": { "description": "List with the delivery addresses selected for the order. We currently only support a single delivery address.", "required": [ "addressType", "addressId", "receiverName", "postalCode", "country" ], "type": "object", "properties": { "addressType": { "type": "string", "description": "String with the address type. The field supports the values: `residential`, `commercial`, `pickup`.", "example": "commercial" }, "addressId": { "type": "string", "description": "String with the address identifier. Optional for `delivery` type orders, and required for `pickup-in-point` orders.", "example": "1" }, "receiverName": { "type": "string", "description": "String with the name of the person responsible for receiving the order.", "example": "Yennefer of Vengerberg" }, "postalCode": { "type": "string", "description": "String with the address' postal code.", "example": "81020-235" }, "city": { "type": "string", "description": "String with the city’s name.", "example": "City" }, "state": { "type": "string", "description": "String with the state's name, filled in with two letter code.", "example": "RJ" }, "country": { "type": "string", "description": "String with the state's name, filled in with three letter code.", "example": "BRA" }, "street": { "type": "string", "description": "String with the street's name.", "example": "The Witcher Avenue" }, "number": { "type": "string", "description": "String with the street's number.", "example": "1986" }, "neighborhood": { "type": "string", "description": "String with the neighborhood's name.", "example": "Neighborhood's name" }, "complement": { "type": "string", "description": "String with the address' complement, like building name, or extra number.", "example": "Complement to address" }, "geoCoordinates": { "$ref": "#/components/schemas/GeoCoordinates" } } }, "GeoCoordinates": { "required": [ "latitude", "longitude" ], "type": "object", "description": "Structure with the address geocoordinates. Optional for `delivery` orders, required for `pickup-in-point` orders.", "properties": { "latitude": { "type": "number", "format": "double", "description": "Double value with the latitude coordinates of the address. Required only if the `geoCoordinates` field is defined." }, "longitude": { "type": "number", "format": "double", "description": "Double value with the longitude coordinates of the address. Required only if the `geoCoordinates` field is defined." } } }, "InvoiceData": { "description": "Object with the order's billing data.", "required": [ "userPaymentInfo" ], "type": "object", "properties": { "userPaymentInfo": { "$ref": "#/components/schemas/UserPaymentInfo" } }, "example": { "userPaymentInfo": { "paymentMethods": [ "creditCardPaymentGroup" ] } } }, "UserPaymentInfo": { "description": "Structure with the order’s payment data. Required only if `invoiceData` is defined.", "required": [ "paymentMethods" ], "type": "object", "properties": { "paymentMethods": { "type": "array", "items": { "type": "string", "description": "Payment method used in the order.", "example": "creditCardPaymentGroup" }, "description": "List of strings with the payment methods used in the order. Required only if `invoiceData` is defined. The format and some possible values of payment methods accepted in this list can be found in the call [Fetching marketplace information with the Orders API](https://developers.vtex.com/vtex-rest-api/docs/get-marketplace-data-orders-api).", "example": [ "creditCardPaymentGroup" ] } }, "example": { "paymentMethods": [ "creditCardPaymentGroup" ] } }, "CustomData": { "description": "Structure with the order's customizable fields. To insert custom fields in the order, you must first go through the process of [Creating an app](https://developers.vtex.com/vtex-rest-api/docs/external-marketplace-integration-app-template), and then adding the app, as well as the desired fields, within the seller's `orderForm`. More information on [Creating customizable fields in the cart with Checkout API](https://developers.vtex.com/vtex-rest-api/docs/customizable-fields-with-checkout-api).", "required": [ "customApps" ], "type": "object", "properties": { "customApps": { "type": "array", "items": { "$ref": "#/components/schemas/CustomApp" }, "description": "Array of objects with information about custom apps." } }, "example": { "customApps": [ { "id": "marketplace-integration", "major": 1, "fields": { "marketplacePaymentMethod": "credit card" } } ] } }, "CustomApp": { "required": [ "id", "major", "fields" ], "type": "object", "description": "Custom application object.", "properties": { "id": { "type": "string", "description": "App's ID.", "example": "ID" }, "major": { "type": "integer", "description": "Integer with the major version of the app. Optional, defaulting to one.", "example": 1 }, "fields": { "$ref": "#/components/schemas/fields" } }, "example": { "id": "marketplace-integration", "major": 1, "fields": { "marketplacePaymentMethod": "credit card" } } }, "fields": { "description": "String dictionary with the names of the fields and their respective values that must be inserted into the order.", "required": [ "marketplacePaymentMethod" ], "type": "object", "properties": { "marketplacePaymentMethod": { "type": "string", "description": "String with field's key and value.", "example": "credit card" } }, "example": { "marketplacePaymentMethod": "credit card" } }, "Deliverybyseller": { "required": [ "marketplaceOrderId", "accountName", "code", "flow", "success", "operationId", "errors", "fields", "message" ], "type": "object", "description": "Object for delivery by seller integration.", "properties": { "marketplaceOrderId": { "type": "string", "nullable": true, "description": "String that indicates the order's ID in the marketplace.", "example": "7e62fcd3-827b-400d-be8a-f050a79c4976" }, "accountName": { "type": "string", "description": "String that indicates which account made the request.", "example": "accountName" }, "code": { "type": "string", "description": "String with a internal Channel Order API code that classifies the response. The possible values returned in this field are described in the [Response Codes]() section.", "example": "SOI001" }, "flow": { "type": "string", "description": "String containing the name of the flow responsible for the response. This field can contain the following values: \n\n`PlaceOrder`: when integrating new orders \n\n`ApproveOrder`: when approving existing orders \n\n`Unknown`: when we’re not able to identify the flow.", "example": "ApproveOrder" }, "success": { "type": "boolean", "description": "Boolean that indicates if the response is successful or not.", "example": true }, "operationId": { "type": "string", "nullable": true, "description": "String GUID that identifies the operation in our service. This field can be used to help us analyze unexpected errors or behaviors.", "example": "1234567" }, "errors": { "type": "array", "nullable": true, "description": "List with errors related to the response, if there's any.", "items": { "type": "object", "description": "Information about an item.", "required": [ "source", "code", "description" ], "properties": { "source": { "type": "string", "description": "Includes the following fields pointing out the context of the error: \n\n`Fulfillment` \n\n`Checkout` \n\n`Order Integration`.", "example": "Fulfillment" }, "code": { "type": "string", "description": "String containing the code returned by the source. Example value: If the source is `Fulfillment`, the code can be FMT005 to indicate that the item(s) in the order are not available.", "enum": ["FMT001", "FMT002", "FMT003", "FMT004", "FMT005"], "example": "FMT005" }, "description": { "type": "string", "description": "String containing the error message and description returned by the source.", "example": "Message describing the error." } }, "example": { "source": "Fulfillment", "code": "FMT005", "description": "Message describing the error." } } }, "fields": { "type": "object", "nullable": true, "description": "Structure with important fields for the connector. This structure is only returned if the response is successful.", "required": [ "mainOrderId" ], "properties": { "mainOrderId": { "type": "string", "description": "String with the order’s ID inside the main seller account in VTEX.", "example": "MKP-123456789" }, "franchiseOrderId": { "type": "string", "description": "String with the order's ID inside the franchise seller account in VTEX. Only returned if the order was integrated using the [Multilevel Omnichannel Inventory](https://help.vtex.com/en/tutorial/multilevel-omnichannel-inventory--7M1xyCZWUyCB7PcjNtOyw4) feature, that is: \n\n- `allowFranchises` field set to `true` when integrating the order \r\n- SLA chosen for the order is from a franchise account.", "example": "432874921387409182347" } } }, "message": { "type": "string", "description": "String with a message explaining the code returned in the response.", "example": "The order was integrated into VTEX successfully" } }, "example": { "marketplaceOrderId": null, "accountName": "grocery1", "code": "SOI003", "flow": "PlaceOrder", "success": true, "operationId": null, "errors": null, "fields": { "mainOrderId": "MKP-123456789", "franchiseOrderId": "432874921387409182347" }, "message": "Order successfully enqueued" } }, "Deliverybyfranchiseseller": { "required": [ "marketplaceOrderId", "accountName", "code", "flow", "success", "operationId", "errors", "fields", "message" ], "type": "object", "description": "Object for delivery by franchise seller.", "properties": { "marketplaceOrderId": { "type": "string", "nullable": true, "description": "String that indicates the order's ID in the marketplace.", "example": "7e62fcd3-827b-400d-be8a-f050a79c4976" }, "accountName": { "type": "string", "description": "String that indicates which account made the request.", "example": "accountName" }, "code": { "type": "string", "description": "String with a internal Channel Order API code that classifies the response. The possible values returned in this field are described in the [Response Codes]() section.", "example": "SOI001" }, "flow": { "type": "string", "description": "String containing the name of the flow responsible for the response. This field can contain the following values: \n\n`PlaceOrder`: when integrating new orders \n\n`ApproveOrder`: when approving existing orders \n\n`Unknown`: when we are not able to identify the flow.", "example": "ApproveOrder" }, "success": { "type": "boolean", "description": "Boolean that indicates if the response is successful or not.", "example": true }, "operationId": { "type": "string", "nullable": true, "description": "String GUID that identifies the operation in our service. This field can be used to help us analyze unexpected errors or behaviors.", "example": "1234567" }, "errors": { "type": "array", "nullable": true, "description": "List with errors related to the response, if there's any.", "items": { "type": "object", "description": "Error details object.", "required": [ "source", "code", "description" ], "properties": { "source": { "type": "string", "description": "Includes the following fields pointing out the context of the error: \n\n`Fulfillment` \n\n`Checkout` \n\n`Order Integration`.", "example": "Fulfillment" }, "code": { "type": "string", "description": "String containing the code returned by the source. Example value: If the source is `Fulfillment`, the code can be FMT005 to indicate that the item(s) in the order are not available.", "example": "FMT005" }, "description": { "type": "string", "description": "String containing the error message/description returned by the source.", "example": "Message describing the error." } }, "example": { "source": "Fulfillment", "code": "FMT005", "description": "Message describing the error." } } }, "fields": { "type": "object", "nullable": true, "description": "Structure with important fields for the connector. This structure is only returned if the response is successful.", "required": [ "mainOrderId" ], "properties": { "mainOrderId": { "type": "string", "description": "String with the order’s ID inside the main seller account in VTEX.", "example": "MKP-123456789" }, "franchiseOrderId": { "type": "string", "description": "String with the order's ID inside the franchise seller account in VTEX. Only returned if the order was integrated using the [Multilevel Omnichannel Inventory](https://help.vtex.com/en/tutorial/multilevel-omnichannel-inventory--7M1xyCZWUyCB7PcjNtOyw4) feature, that is: \n\n- `allowFranchises` field set to `true` when integrating the order \r\n- SLA chosen for the order is from a franchise account.", "example": "432874921387409182347" } } }, "message": { "type": "string", "description": "String with a message explaining the code returned in the response.", "nullable": true, "example": "The order was integrated into VTEX successfully" } }, "example": { "marketplaceOrderId": null, "accountName": "grocery1", "code": "SOI003", "flow": "PlaceOrder", "success": true, "operationId": null, "errors": null, "fields": { "mainOrderId": "MKP-123456789", "franchiseOrderId": "432874921387409182347" }, "message": "Order successfully enqueued" } }, "UpdateOrderStatusRequest": { "required": [ "marketplaceOrderId", "marketplaceOrderStatus", "connectorName", "connectorEndpoint" ], "description": "Object for updating the status of an order in the marketplace.", "type": "object", "properties": { "marketplaceOrderId": { "type": "string", "description": "String that indicates the order's ID in the marketplace.", "example": "7e62fcd3-827b-400d-be8a-f050a79c4976" }, "marketplaceOrderStatus": { "type": "string", "description": "Required field including a string with the order’s status in the marketplace. If you send an order with the status `APPROVED` to integrate, our service will automatically try to advance its status in VTEX after integrating it.", "enum": [ "new", "approved"], "example": "new" }, "connectorName": { "type": "string", "description": "String with the identifier code of the connector responsible for the order. \n\nThis field is optional if the connector uses the [App Template](https://developers.vtex.com/vtex-rest-api/docs/external-marketplace-integration-app-template) and authenticates on our request via `VtexIdclientAutCookie`. \n\nIt is required if the connector is native or does not use the App Template.", "example": "connectorName" }, "connectorEndpoint": { "type": "string", "description": "String with the connector's base endpoint that will receive notifications about the orders processing results, as well as status updates from VTEX OMS. This field does not accept query strings. You can use the models below: \n\n- `https://{{externalconnector}}.com` \n\n- `https://{{externalconnector.com}}/api/vtex` if you additionaly want to send a relative URL with the endpoint. \n\nThis field is optional if the connector uses the [App Template](https://developers.vtex.com/vtex-rest-api/docs/external-marketplace-integration-app-template) and authenticates on our request via `VtexIdclientAutCookie`. \n\nIt is required if the connector is native or does not use the App Template.", "example": "https://{{externalconnector.com}}/api/vtex" } }, "example": { "marketplaceOrderId": "{{$guid}}", "marketplaceOrderStatus": "approved", "connectorName": "Skyhub", "connectorEndpoint": "https://connector-endpoint.com/api/vtex" } }, "Approveorder": { "description": "Object for approving an order. Contains information about the approval status, errors (if any), and additional fields related to the approval process.", "required": [ "marketplaceOrderId", "accountName", "code", "flow", "success", "operationId", "errors", "fields", "message" ], "type": "object", "properties": { "marketplaceOrderId": { "type": "string", "nullable": true, "description": "String that indicates the order's ID in the marketplace.", "example": "7e62fcd3-827b-400d-be8a-f050a79c4976" }, "accountName": { "type": "string", "description": "String that indicates which account made the request.", "example": "accountName", "nullable": true }, "code": { "type": "string", "description": "String with a internal Channel Order API code that classifies the response. The possible values returned in this field are described in the Response Codes section of this API Reference.", "example": "SOI001" }, "flow": { "type": "string", "description": "String containing the name of the flow responsible for the response. This field can contain the following values: \n\n`PlaceOrder`: when integrating new orders. \n\n`ApproveOrder`: when approving existing orders. \n\n`Unknown`: when we’re not able to identify the flow.", "example": "ApproveOrder" }, "success": { "type": "boolean", "description": "Boolean that indicates if the response is successful or not.", "example": true }, "operationId": { "type": "string", "nullable": true, "description": "String GUID that identifies the operation in our service. This field can be used to help us analyze unexpected errors or behaviors.", "example": "1234567" }, "errors": { "type": "array", "nullable": true, "description": "List with errors related to the response, if there is any.", "items": { "type": "object", "description": "Object representing an error in the response.", "required": [ "source", "code", "description" ], "properties": { "source": { "type": "string", "description": "Includes the following fields pointing out the context of the error: \n\n`Fulfillment` \n\n`Checkout` \n\n`Order Integration`.", "enum": ["Fulfillment", "Checkout", "Order Integration"], "example": "Fulfillment" }, "code": { "type": "string", "description": "String containing the code returned by the source. Example value: If the source is `Fulfillment`, the code can be FMT005 to indicate that the item(s) in the order are not available.", "example": "FMT005" }, "description": { "type": "string", "description": "String containing the error message and description returned by the source.", "example": "Message describing the error." } }, "example": { "source": "Fulfillment", "code": "FMT005", "description": "Message describing the error." } } }, "fields": { "type": "object", "nullable": true, "description": "Structure with important fields for the connector. This structure is only returned if the response is successful. Includes the following fields: \n\n`mainOrderId`: String with the order's ID inside the main seller account in VTEX. \n\n`franchiseOrderId`: - String with the order's ID inside the franchise seller account in VTEX. Only returned if the order was integrated using the [Multilevel Omnichannel Inventory](https://help.vtex.com/en/tutorial/multilevel-omnichannel-inventory--7M1xyCZWUyCB7PcjNtOyw4) feature, that is: \n\n- `allowFranchises` field set to `true` when integrating the order \n\n- `SLA` chosen for the order is from a franchise account.", "properties": { "mainOrderId": { "type": "string", "description": "String with the order’s ID inside the main seller account in VTEX.", "example": "MKP-123456789" }, "franchiseOrderId": { "type": "string", "description": "String with the order's ID inside the franchise seller account in VTEX. Only returned if the order was integrated using the [Multilevel Omnichannel Inventory](https://help.vtex.com/en/tutorial/multilevel-omnichannel-inventory--7M1xyCZWUyCB7PcjNtOyw4) feature.", "example": "432874921387409182347" } }, "example": { "franchiseOrderId": "38475934875" } }, "message": { "type": "string", "description": "String with a message explaining the code returned in the response.", "example": "The order was integrated into VTEX successfully" } }, "example": { "marketplaceOrderId": "7e62fcd3-827b-400d-be8a-f050a79c4976", "accountName": null, "code": "SOI003", "flow": "ApproveOrder", "success": true, "operationId": null, "errors": null, "fields": null, "message": "Order successfully enqueued" } }, "orderIDFulfillmentResponse": { "type": "object", "description": "Response schema for a successful order creation.", "properties": { "status": { "type": "string", "description": "Indicates the success status of the response." }, "message": { "type": "string", "description": "A message providing additional information about the response." }, "orderId": { "type": "string", "description": "The unique identifier of the created order." }, "details": { "type": "object", "description": "Detailed information about the created order.", "properties": { "createdAt": { "type": "string", "description": "The timestamp when the order was created. Format: `YYYY/MM/DD HH:MM:SSZ`." }, "marketplaceOrderId": { "type": "string", "description": "The marketplace-specific order identifier." }, "status": { "type": "string", "description": "The current status of the order." } } } } }, "placeFulfillmentOrderRequest": { "type": "object", "description": "Request schema for placing a fulfillment order.", "required": [ "marketplaceOrderId", "marketplaceServicesEndpoint", "marketplacePaymentValue", "items", "clientProfileData", "shippingData" ], "properties": { "marketplaceOrderId": { "type": "string", "description": "ID of the order in the marketplace.", "example": "123456789" }, "marketplaceServicesEndpoint": { "type": "string", "description": "Endpoint provided by the marketplace for post purchase communication. Should be an URL, containing protocol, host, path and query string (in case it applies).", "example": "https://exampleseller.marketplaceservices.com" }, "marketplacePaymentValue": { "type": "integer", "description": "Value of the payment made to the marketplace.", "example": 100 }, "isCreatedAsync": { "type": "boolean", "description": "Indicates whether an order is created. It must be `true` if an order is being placed with [Price divergence](https://help.vtex.com/en/tutorial/configuring-price-divergence-rule--awAKP0sS5J8jgLs2g7pPe), otherwise the request will not work.", "example": false }, "items": { "type": "array", "description": "Array of objects containing information on each of the order's items.", "items": { "type": "object", "description": "An object representing the items in the cart for simulation, including details such as SKU ID, quantity, seller information, pricing, commissions, and any associated services or attachments.", "required": [ "id", "quantity", "seller" ], "properties": { "id": { "type": "string", "description": "The SKU ID.", "example": "123" }, "quantity": { "type": "integer", "format": "int32", "description": "The quantity of items of this specific SKU in the cart to be simulated.", "example": 1 }, "seller": { "type": "string", "description": "The ID of the seller responsible for this SKU. This ID can be found in your VTEX Admin.", "example": "1" }, "commission": { "type": "integer", "description": "Comission.", "example": 10 }, "freightCommission": { "type": "integer", "description": "Freight comission.", "example": 10 }, "price": { "type": "integer", "description": "Item price within the context of the order without separating 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": { "type": "object", "description": "Object that represents items from the `bundleItems` field.", "properties": { "type": { "type": "string", "description": "Service type.", "example": "type-example" }, "id": { "type": "integer", "description": "Service identifier.", "example": 1034 }, "name": { "type": "string", "description": "Service name.", "example": "name-example" }, "price": { "type": "integer", "description": "Service price. The last two digits are the cents.", "example": 199 } } } }, "itemAttachment": { "type": "object", "description": "Item attachment.", "properties": { "name": { "type": "string", "description": "Attachment name.", "example": "name-example" }, "content": { "type": "string", "description": "Content referring to the customization requested by the customer.", "example": "content-example" } } }, "attachments": { "type": "array", "description": "Array containing information on attachments.", "items": { "description": "A string representing a single attachment associated with the item, providing additional details or customizations.", "type": "string" } }, "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": "Array of price tags that modify the price, such as discounts or rates applicable to the item in the order context.", "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.", "default": false, "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 whether the order is a gift.", "default": false, "example": false } }, "example": { "id": "123456789", "quantity": 1, "seller": "1" } } }, "clientProfileData": { "type": "object", "description": "Customer's profile information.", "required": [ "email", "firstName", "lastName", "documentType", "document" ], "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 informed by the customer. Validation depends on the country.", "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.", "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", "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. Validation depends on the country.", "example": "12345000" }, "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": "Array with two strings with geocoordinates, first latitude, then longitude.", "items": { "type": "string", "description": "A string representing the longitude coordinate.", "example": "00.00000" } } } }, "logisticsInfo": { "type": "array", "description": "Array of objects containing logistics information of each item.", "items": { "type": "object", "description": "An object representing logistics information for a specific item in the order or cart, including its index, selected shipping service level agreement (SLA), and associated price.", "required": [ "itemIndex", "selectedSla", "price" ], "properties": { "itemIndex": { "type": "integer", "description": "Index of the item in the `items` array, starting at `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": "In case of scheduled delivery, this object will contain information on the delivery window selected by the shopper.", "properties": { "startDateUtc": { "type": "string", "description": "Delivery window start day and time in UTC, as `YYYY-DD-MM HH:MM:SS`." }, "endDateUtc": { "type": "string", "description": "Delivery window end day and time in UTC, as `YYYY-DD-MM HH:MM:SS`." }, "price": { "type": "integer", "description": "Delivery window price.", "default": 0 }, "lisPrice": { "type": "integer", "description": "Delivery window list price.", "default": 0 }, "tax": { "type": "integer", "description": "Delivery window tax.", "default": 0 } } } } } }, "updateStatus": { "type": "string", "description": "Indicates whether this object's information is current according to the order's items. An order can not be placed if `\"outdated\"`." } } }, "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, "default": null }, "marketingData": { "type": "object", "description": "An object containing various marketing data parameters used to track and analyze the source, medium, campaign, and internal UTMI parameters related to the order or cart.", "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" } } }, "placeFulfillmentOrderResponse": { "type": "object", "description": "Response schema for placing a fulfillment order.", "properties": { "orderId": { "type": "string", "description": "ID of the created order." }, "status": { "type": "string", "description": "Status of the order creation." }, "message": { "type": "string", "description": "Response message providing additional information about the order creation." }, "orderData": { "type": "object", "description": "Data related to the created order.", "properties": { "marketplaceOrderId": { "type": "string", "description": "ID of the order in the marketplace." }, "marketplaceServicesEndpoint": { "type": "string", "description": "Endpoint provided by the marketplace for post purchase communication. Should be an URL, containing protocol, host, path and query string (in case it applies)." }, "marketplacePaymentValue": { "type": "integer", "description": "Value of the payment made to the marketplace." }, "isCreatedAsync": { "type": "boolean", "description": "Indicates whether an order is created. It must be `true` if an order is being placed with price divergence, otherwise the request will not work." }, "items": { "type": "array", "description": "List of items included in the order.", "items": { "type": "object", "description": "Information about a specific item in the order.", "properties": { "id": { "type": "string", "description": "The SKU ID." }, "quantity": { "type": "integer", "description": "The quantity of items of this specific SKU in the cart to be simulated." }, "seller": { "type": "string", "description": "The ID of the seller responsible for this SKU. This ID can be found in your VTEX Admin." }, "commission": { "type": "integer", "description": "Commission." }, "freightCommission": { "type": "integer", "description": "Freight commission." }, "price": { "type": "integer", "description": "Item price within the context of the order without separating cents. For example, $24.99 is represented `2499`." }, "bundleItems": { "type": "array", "description": "Information on services sold along with the SKU. Example: a gift package.", "items": { "type": "object", "description": "Information about a bundled item or service.", "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": "Item attachment.", "properties": { "name": { "type": "string", "description": "Attachment name." }, "content": { "type": "string", "description": "Content referring to the customization requested by the customer." } } }, "attachments": { "type": "array", "description": "Array containing information on attachments.", "items": { "description": "A string representing a single attachment associated with the item, providing additional details or customizations.", "type": "string" } }, "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": "Array of price tags that modify the price, such as discounts or rates applicable to the item in the order context.", "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": "Indicates whether the order is a gift." } } } }, "clientProfileData": { "type": "object", "description": "Customer's profile information.", "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 informed by the customer. Validation depends on the country." }, "phone": { "type": "string", "description": "Customer's phone number." }, "corporateName": { "type": "string", "description": "Company name, if the customer is a legal entity." }, "tradeName": { "type": "string", "description": "Trade name, if the customer is a legal entity." }, "corporateDocument": { "type": "string", "description": "Corporate document, if the customer is a legal entity." }, "stateInscription": { "type": "string", "description": "State inscription, if the customer is a legal entity." }, "corporatePhone": { "type": "string", "description": "Corporate phone number, if the customer is a legal entity." }, "isCorporate": { "type": "boolean", "description": "`true` if the customer is a legal entity." } } }, "shippingData": { "type": "object", "description": "Shipping information.", "properties": { "address": { "type": "object", "description": "Shipping address.", "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. Validation depends on the country." }, "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": "Array with two strings with geocoordinates, first latitude, then longitude.", "items": { "type": "string", "description": "A string representing the longitude coordinate." } } } }, "logisticsInfo": { "type": "array", "description": "Array of objects containing logistics information of each item.", "items": { "type": "object", "description": "Logistics information for a specific item in the order.", "properties": { "itemIndex": { "type": "integer", "description": "Index of the item in the logistics chain." }, "selectedSla": { "type": "string", "description": "Selected service level agreement (SLA) for the item." }, "lockTTL": { "type": "string", "description": "Time to live (TTL) of the lock until it is confirmed." }, "shippingEstimate": { "type": "string", "description": "Estimated shipping time." }, "price": { "type": "integer", "description": "Price of the logistics chain." }, "deliveryWindow": { "type": "object", "description": "Delivery window object.", "properties": { "startDateUtc": { "type": "string", "description": "Start date of the delivery window in UTC." }, "endDateUtc": { "type": "string", "description": "End date of the delivery window in UTC." }, "price": { "type": "integer", "description": "Delivery price." }, "lisPrice": { "type": "integer", "description": "LIS price." }, "tax": { "type": "integer", "description": "Tax." } } } } } }, "updateStatus": { "type": "string", "description": "Update status of the shipping order." } } }, "paymentData": { "type": "string", "description": "Payment information." }, "marketingData": { "type": "object", "description": "Marketing data related to the order.", "properties": { "utmSource": { "type": "string", "description": "UTM source parameter for marketing analysis." }, "utmMedium": { "type": "string", "description": "UTM medium parameter for marketing analysis." }, "utmCampaign": { "type": "string", "description": "UTM campaign parameter for marketing analysis." }, "utmiPage": { "type": "string", "description": "UTMI page parameter for marketing analysis." }, "utmiPart": { "type": "string", "description": "UTMI part parameter for marketing analysis." }, "utmiCampaign": { "type": "string", "description": "UTMI campaign parameter for marketing analysis." } } }, "openTextField": { "type": "string", "description": "Additional information." } } } } }, "TaxData": { "required": [ "skuId", "value" ], "type": "object", "description": "Object with tax information for a specific SKU in the order.", "properties": { "skuId": { "type": "string", "description": "String with the SKU ID in VTEX's catalog." }, "value": { "type": "integer", "description": "Integer with the tax value applied to the SKU. If the value is `USD1.50`, convert it to `150`." } }, "example": { "skuId": "1", "value": 150 } }, "TrackingHint": { "required": [ "trackingId", "courierName" ], "type": "object", "description": "Object with tracking information hints for the order's shipment.", "properties": { "trackingId": { "type": "string", "description": "String with the shipment tracking identifier." }, "courierName": { "type": "string", "description": "String with the name of the courier responsible for the delivery." }, "trackingUrl": { "type": "string", "format": "uri", "description": "String with the URL to track the shipment." }, "trackingLabel": { "type": "string", "description": "String with the label or display name for the tracking." } }, "example": { "trackingId": "BR123456789", "courierName": "Correios", "trackingUrl": "https://tracking.example.com/BR123456789", "trackingLabel": "Correios Express" } } }, "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey" }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken" } } }, "tags": [ { "name": "External Marketplace" } ] }