{"openapi":"3.0.0","servers":[{"url":"https://vtex.local"},{"description":"","url":"/"}],"x-hasEquivalentPaths":true,"info":{"contact":{},"description":"\r\nThe _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/vtex-rest-api/reference/fulfillment-simulation) | Marketplace | Seller |\r\n| [Order placement](https://developers.vtex.com/vtex-rest-api/reference/order-placement) | Marketplace | Seller |\r\n| [Authorize fulfillment](https://developers.vtex.com/vtex-rest-api/reference/authorize-fulfillment) | Marketplace | Seller |\r\n| [Marketplace order cancellation](https://developers.vtex.com/vtex-rest-api/reference/marketplace-order-cancellation) | Marketplace | Seller |\r\n| [Send invoice](https://developers.vtex.com/vtex-rest-api/reference/send-invoice) | Seller | Marketplace |\r\n| [Send tracking information](https://developers.vtex.com/vtex-rest-api/reference/send-tracking-information) | Seller      | Marketplace |\r\n| [Update tracking status](https://developers.vtex.com/vtex-rest-api/reference/update-tracking-status) | Seller | Marketplace |\r\n| [Cancel order in marketplace](https://developers.vtex.com/vtex-rest-api/reference/cancel-order-in-marketplace) | 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/vtex-rest-api/reference/vtex-mapper-registration) | External marketplace | VTEX system |\r\n| [Send Category Mapping to VTEX Mapper](https://developers.vtex.com/vtex-rest-api/reference/send-category-mapping-to-vtex-mapper) |  External marketplace | VTEX system |\r\n| [Authorize fulfillment](https://developers.vtex.com/vtex-rest-api/reference/authorize-fulfillment) | Marketplace | Seller |\r\n| [Place fulfillment order](https://developers.vtex.com/vtex-rest-api/reference/place-fulfillment-order)   | External marketplace | VTEX Seller |\r\n| [Authorize dispatch for fulfillment order](https://developers.vtex.com/vtex-rest-api/reference/authorize-dispatch-for-fulfillment-order) | 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).","title":"Marketplace Protocol","version":"1.0","x-origin":[{"format":"openapi","url":"https://raw.githubusercontent.com/vtex/openapi-schemas/master/VTEX - Marketplace Protocol.json","version":"3.0"}],"x-providerName":"vtex.local","x-serviceName":"Marketplace-Protocol"},"security":[{"appKey":[],"appToken":[]}],"tags":[{"name":"External Seller"},{"name":"External Marketplace"}],"paths":{"/api/checkout/pub/orderForms/simulation":{"post":{"deprecated":false,"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.","operationId":"fulfillment-simulation-external-marketplace","parameters":[{"description":"Type of the content being sent.","in":"header","name":"Content-Type","required":true,"schema":{"default":"application/json","type":"string"},"style":"simple"},{"description":"HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.","in":"header","name":"Accept","required":true,"schema":{"default":"application/json","type":"string"},"style":"simple"},{"description":"The affiliate ID code created by the seller.","in":"query","name":"affiliateId","required":false,"schema":{"default":"MNF","type":"string"},"style":"form"},{"description":"Trade Policy (Sales Channel) identification.","in":"query","name":"sc","required":false,"schema":{"example":1,"type":"integer"},"style":"form"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"clientProfileData":{"description":"Customer's profile information.","properties":{"corporateDocument":{"description":"Corporate document, if the customer is a legal entity.","nullable":true,"type":"string"},"corporateName":{"description":"Company name, if the customer is a legal entity.","nullable":true,"type":"string"},"corporatePhone":{"description":"Corporate phone number, if the customer is a legal entity.","nullable":true,"type":"string"},"customerClass":{"description":"Customer class.","nullable":true,"type":"string"},"document":{"description":"Document informed by the customer.","example":"12345678900","type":"string"},"documentType":{"description":"Type of the document informed by the customer.","example":"cpf","type":"string"},"email":{"description":"Email address.","example":"clark.kent@example.com","type":"string"},"firstName":{"description":"First name.","example":"Clark","type":"string"},"isCorporate":{"description":"Indicates whether the customer is a legal entity.","type":"boolean"},"lastName":{"description":"Last name.","example":"Kent","type":"string"},"phone":{"description":"Phone number.","example":"+552199999999","type":"string"},"profileCompleteOnLoading":{"description":"Indicates whether profile is complete on loading.","type":"boolean"},"profileErrorOnLoading":{"description":"Indicates whether profile presents error on loading.","nullable":true,"type":"boolean"},"stateInscription":{"description":"State inscription, if the customer is a legal entity.","nullable":true,"type":"string"},"tradeName":{"description":"Trade name, if the customer is a legal entity.","nullable":true,"type":"string"}},"type":"object"},"country":{"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","type":"string"},"geoCoordinates":{"default":[-47.924747467041016,-15.832582473754883],"description":"Array containing two floats with geocoordinates, first longitude, then latitude.","items":{"example":-47.924747467041016,"type":"number"},"type":"array"},"isCheckedIn":{"default":false,"description":"Indicates whether order is checked in.","type":"boolean"},"items":{"description":"Array containing information about the SKUs inside the cart to be simulated.","items":{"properties":{"id":{"description":"The SKU ID.","example":"1","type":"string"},"quantity":{"description":"The quantity of items of this specific SKU in the cart to be simulated.","example":1,"format":"int32","type":"integer"},"seller":{"description":"The ID of the seller responsible for this SKU. This ID can be found in your VTEX Admin.","example":"1","type":"string"}},"type":"object"},"type":"array"},"marketingData":{"description":"Object containing promotion data such as coupon tracking information and internal or external UTMs.","properties":{"coupon":{"default":"free-shipping","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.","type":"string"},"utmCampaign":{"default":"Black friday","description":"UTM campaign","type":"string"},"utmMedium":{"default":"CPC","description":"UTM medium.","type":"string"},"utmSource":{"default":"Facebook","description":"UTM source.","type":"string"},"utmiCampaign":{"default":"utmi_campaign-example","description":"utmi_campaign (internal utm).","type":"string"},"utmiPage":{"default":"utmi_page-example","description":"utmi_page (internal utm).","type":"string"},"utmiPart":{"default":"utmi_part-example","description":"utmi_part (internal utm).","type":"string"}},"type":"object"},"postalCode":{"description":"Postal code.","example":"12345-000","type":"string"},"selectedSla":{"description":"SLA selected by the customer.","example":"Normal","type":"string"},"storeId":{"description":"ID of the store.","nullable":true,"type":"string"}},"required":["id","quantity","seller"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"example":{"country":"BRA","geoCoordinates":[-47.924747467041016,-15.832582473754883],"itemMetadata":{"items":[{"assemblyOptions":[{"composition":null,"id":"T-Shirt Customization","inputValues":{"T-Shirt Name":{"domain":["[]"],"maximumNumberOfCharacters":2}},"name":"T-Shirt Customization","required":false}],"id":"1","seller":"1"}]},"items":[{"availability":"available","id":"1","listPrice":9999,"measurementUnit":"un","offerings":[],"parentAssemblyBinding":null,"parentItemIndex":null,"price":9999,"priceDefinition":{"calculatedSellingPrice":2999700,"sellingPrices":[{"quantity":1,"value":2999700}],"total":2999700},"priceTags":[{"identifier":"1234abc-5678b-1234c","isPercentual":false,"name":"DISCOUNT@MANUALPRICE","rawValue":-50,"value":-5000}],"priceValidUntil":"2025-08-15T13:51:41.074Z","quantity":1,"requestIndex":0,"rewardValue":0,"seller":"1","sellerChain":["1"],"sellingPrice":2999700,"tax":0,"unitMultiplier":300}],"logisticsInfo":[{"addressId":null,"deliveryChannels":[{"id":"pickup-in-point"},{"id":"delivery"}],"itemIndex":0,"quantity":1,"selectedDeliveryChannel":null,"selectedSla":null,"shipsTo":["BRA"],"slas":[{"availableDeliveryWindows":{"endDateUtc":"2025-08-15T13:51:41.074Z","lisPrice":0,"price":0,"startDateUtc":"2025-08-15T13:51:41.074Z","tax":0},"deliveryChannel":"delivery","deliveryIds":[{"courierId":"1","courierName":"Transportadora","dockId":"1","kitItemDetails":[],"quantity":1,"warehouseId":11}],"deliveryWindow":{"endDateUtc":"2025-08-15T13:51:41.074Z","listprice":1000,"price":0,"startDateUtc":"2025-08-15T13:51:41.074Z","tax":0},"id":"Normal","listPrice":1500,"lockTTL":"10d","name":"Normal","pickupDistance":0,"pickupPointId":null,"pickupStoreInfo":{"additionalInfo":null,"address":null,"dockId":null,"friendlyName":null,"isPickupStore":false},"polygonName":null,"price":1500,"shippingEstimate":"3bd","shippingEstimateDate":null,"tax":0,"transitTime":"3bd"}]}],"marketingData":{"coupon":null,"marketingTags":["tag1","tag2"],"utmCampaign":"Black friday","utmMedium":"CPC","utmSource":"app","utmiCampaign":"true","utmiPart":"true","utmipage":"true"},"messages":[],"paymentData":{"availableAccounts":[],"availableAssociations":{},"availableTokens":[],"giftCardMessages":[],"giftCards":[],"installmentOptions":[{"bin":null,"installments":[{"count":1,"hasInterestRate":false,"interestRate":0,"sellerMerchantInstallments":[{"count":1,"hasInterestRate":false,"id":"LOJADOBRENO","interestRate":0,"total":2999700,"value":2999700}],"total":2999700,"value":2999700}],"paymentGroupName":"creditCardPaymentGroup","paymentName":"Visa","paymentSystem":"2","value":2999700},{"bin":null,"installments":[{"count":1,"hasInterestRate":false,"interestRate":0,"sellerMerchantInstallments":[{"count":1,"hasInterestRate":false,"id":"LOJADOBRENO","interestRate":0,"total":2999700,"value":2999700}],"total":2999700,"value":2999700}],"paymentGroupName":"bankInvoicePaymentGroup","paymentName":"Boleto Bancário","paymentSystem":"6","value":2999700},{"bin":null,"installments":[{"count":1,"hasInterestRate":false,"interestRate":0,"sellerMerchantInstallments":[{"count":1,"hasInterestRate":false,"id":"LOJADOBRENO","interestRate":0,"total":2999700,"value":2999700}],"total":2999700,"value":2999700}],"paymentGroupName":"MercadoPagoProPaymentGroup","paymentName":"MercadoPagoPro","paymentSystem":"127","value":2999700},{"bin":null,"installments":[{"count":1,"hasInterestRate":false,"interestRate":0,"sellerMerchantInstallments":[{"count":1,"hasInterestRate":false,"id":"LOJADOBRENO","interestRate":0,"total":2999700,"value":2999700}],"total":2999700,"value":2999700}],"paymentGroupName":"custom202PaymentGroupPaymentGroup","paymentName":"Dinheiro","paymentSystem":"202","value":2999700}],"paymentSystems":[{"availablePayments":null,"description":"","displayDocument":false,"dueDate":"2025-08-15T13:51:41.074Z","groupName":"custom202PaymentGroupPaymentGroup","id":202,"isCustom":true,"name":"Dinheiro","requiresAuthentication":false,"requiresDocument":false,"stringId":"202","template":"custom202PaymentGroupPaymentGroup-template","validator":null},{"availablePayments":null,"description":"","displayDocument":false,"dueDate":"2025-08-15T13:51:41.074Z","groupName":"bankInvoicePaymentGroup","id":6,"isCustom":false,"name":"Boleto Bancário","requiresAuthentication":false,"requiresDocument":false,"stringId":"6","template":"bankInvoicePaymentGroup-template","validator":null},{"availablePayments":null,"description":"","displayDocument":false,"dueDate":"2025-08-15T13:51:41.074Z","groupName":"creditCardPaymentGroup","id":2,"isCustom":false,"name":"Visa","requiresAuthentication":false,"requiresDocument":false,"stringId":"2","template":"creditCardPaymentGroup-template","validator":null},{"availablePayments":null,"description":"","displayDocument":false,"dueDate":"2025-08-15T13:51:41.074Z","groupName":"MercadoPagoProPaymentGroup","id":127,"isCustom":false,"name":"MercadoPagoPro","requiresAuthentication":false,"requiresDocument":false,"stringId":"127","template":"MercadoPagoProPaymentGroup-template","validator":null}],"payments":[]},"pickupPoints":[],"postalCode":"12345-000","purchaseConditions":{"itemPurchaseConditions":[{"id":"1","listPrice":9999,"price":9999,"seller":"1","sellerChain":["1"],"slas":[{"availableDeliveryWindows":{"endDateUtc":"2025-08-15T13:51:41.074Z","lisPrice":0,"price":0,"startDateUtc":"2025-08-15T13:51:41.074Z","tax":0},"deliveryChannel":"delivery","deliveryIds":[{"courierId":"1","courierName":"Transportadora","dockId":"1","kitItemDetails":[],"quantity":1,"warehouseId":11}],"deliveryWindow":{"endDateUtc":"2025-08-15T13:51:41.074Z","listprice":1000,"price":0,"startDateUtc":"2025-08-15T13:51:41.074Z","tax":0},"id":"Normal","listPrice":1500,"lockTTL":"10d","name":"Normal","pickupDistance":0,"pickupPointId":null,"pickupStoreInfo":{"additionalInfo":null,"address":null,"dockId":null,"friendlyName":null,"isPickupStore":false},"polygonName":null,"price":1500,"shippingEstimate":"3bd","shippingEstimateDate":null,"tax":0,"transitTime":"3bd"}]}]},"ratesAndBenefitsData":{"rateAndBenefitsIdentifiers":[],"teaser":[]},"selectableGifts":[],"subscriptionData":null,"totals":[{"id":"Items","name":"Total dos Itens","value":2999700}]},"schema":{"properties":{"country":{"description":"Three letter ISO code of the country of the shipping address.","type":"string"},"items":{"description":"Information on each item in the cart.","items":{"properties":{"availability":{"description":"Availability.","type":"string"},"id":{"description":"ID of the item.","type":"string"},"listPrice":{"description":"List price in cents.","type":"integer"},"measurementUnit":{"description":"Measurement unit.","type":"string"},"offerings":{"description":"Array containing offering information.","items":{},"type":"array"},"parentAssemblyBinding":{"description":"Parent assembly binding.","nullable":true,"type":"string"},"parentItemIndex":{"description":"Parent item index.","nullable":true,"type":"integer"},"price":{"description":"Price in cents.","type":"integer"},"priceDefinition":{"description":"Price information for all units of a specific item.","properties":{"calculatedSellingPrice":{"description":"Item's calculated unitary selling price in cents.","type":"integer"},"sellingPrices":{"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":{"properties":{"quantity":{"description":"Rounding quantity, meaning how many items are rounded to this value.","type":"integer"},"value":{"description":"Value in cents for that specific rounding.","type":"integer"}},"type":"object"},"type":"array"},"total":{"description":"Total value for all units of the item in cents.","type":"integer"}},"type":"object"},"priceTags":{"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":{"properties":{"identifier":{"description":"Price tag identifier.","type":"string"},"isPercentual":{"description":"Indicates whether price tag value is applied through a percentage.","type":"boolean"},"name":{"description":"Price tag name.","type":"string"},"owner":{"description":"Identification of the responsible for the price tag.","type":"string"},"rawValue":{"description":"Price tag raw value.","type":"integer"},"value":{"description":"Price tag value.","type":"integer"}},"type":"object"},"type":"array"},"priceValidUntil":{"description":"Price expiration date and time.","type":"string"},"quantity":{"description":"The quantity of the item the cart.","type":"integer"},"requestIndex":{"description":"Request index information.","type":"integer"},"rewardValue":{"description":"Reward value in cents.","type":"integer"},"seller":{"description":"The seller responsible for the SKU.","type":"string"},"sellerChain":{"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":{"description":"Seller.","type":"string"},"type":"array"},"sellingPrice":{"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.","type":"integer"},"tax":{"description":"Tax value in cents.","type":"integer"},"unitMultiplier":{"description":"Unit multiplier.","type":"integer"}},"type":"object"},"type":"array"},"logisticsInfo":{"description":"Array with logistics information on each item of the `items` array in the `orderForm`.","items":{"properties":{"addressId":{"description":"Address ID.","nullable":true,"type":"string"},"deliveryChannels":{"description":"List of available delivery channels.","items":{"properties":{"id":{"description":"Delivery channel ID.","type":"string"}},"type":"object"},"type":"array"},"itemIndex":{"description":"Index of item in items array.","type":"integer"},"itemMetadata":{"description":"Item metadata.","properties":{"items":{"description":"List of objects containing metadata on each item in the order.","items":{"properties":{"assemblyOptions":{"description":"Assembly options information.","items":{},"properties":{"composition":{"description":"Composition information.","nullable":true,"type":"string"},"id":{"description":"Item ID.","type":"string"},"inputValues":{"description":"Input values information.","type":"object"},"name":{"description":"Item name.","type":"string"},"required":{"description":"Indicates whether the item is required.","type":"boolean"}},"type":"array"},"id":{"description":"Item ID.","type":"string"},"seller":{"description":"Seller.","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"messages":{"description":"Array containing an object for each message generated by our servers while processing the request.","items":{},"type":"array"},"pickupPoints":{"description":"Array containing pickup points information.","items":{},"type":"array"},"purchaseConditions":{"description":"Purchase conditions information.","properties":{"itemPurchaseConditions":{"description":"List of objects containing purchase condition information on each item in the order.","items":{"properties":{"id":{"description":"Item ID.","type":"string"},"listPrice":{"description":"List price in cents.","type":"integer"},"price":{"description":"Price in cents.","type":"integer"},"seller":{"description":"Seller.","type":"string"},"sellerChain":{"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":"array"},"slas":{"description":"Information on available SLAs.","items":{"properties":{"availableDeliveryWindows":{"description":"This object contains information about the delivery window available to the shopper.","properties":{"endDateUtc":{"description":"Delivery window ending day and time in UTC.","type":"string"},"lisPrice":{"description":"Delivery window list price.","type":"integer"},"price":{"description":"Delivery window price.","type":"integer"},"startDateUtc":{"description":"Delivery window starting day and time in UTC.","type":"string"},"tax":{"description":"Delivery window tax.","type":"integer"}},"type":"object"},"deliveryChannel":{"description":"Delivery channel.","type":"string"},"deliveryIds":{"description":"Information on each delivery ID.","items":{"properties":{"courierId":{"description":"Courier ID.","type":"string"},"courierName":{"description":"Courier name.","type":"string"},"dockId":{"description":"Warehouse ID.","type":"string"},"quantity":{"description":"Quantity.","type":"integer"},"warehouseId":{"description":"Warehouse ID.","type":"string"}},"type":"object"},"type":"array"},"deliveryWindow":{"description":"In case of scheduled delivery, this object will contain information on the delivery window selected by the shopper.","properties":{"endDateUtc":{"description":"Delivery window ending day and time in UTC.","type":"string"},"lisPrice":{"description":"Delivery window list price.","type":"integer"},"price":{"description":"Delivery window price.","type":"integer"},"startDateUtc":{"description":"Delivery window starting day and time in UTC.","type":"string"},"tax":{"description":"Delivery window tax.","type":"integer"}},"type":"object"},"id":{"description":"SLA ID.","type":"string"},"listPrice":{"description":"List price in cents.","type":"integer"},"lockTTL":{"description":"Estimate date of delivery.","type":"string"},"name":{"description":"SLA name.","type":"string"},"pickupDistance":{"description":"Pickup point distance.","type":"integer"},"pickupPointId":{"description":"Pickup point ID.","nullable":true,"type":"string"},"pickupStoreInfo":{"description":"Information on the pickup store.","properties":{"additionalInfo":{"description":"Additional information.","nullable":true,"type":"string"},"address":{"description":"Address information.","nullable":true,"type":"object"},"dockId":{"description":"Corresponding dock ID.","nullable":true,"type":"string"},"friendlyName":{"description":"Friendly name.","nullable":true,"type":"string"},"isPickupStore":{"description":"Indicates whether it is the pickup store.","type":"boolean"}},"type":"object"},"polygonName":{"description":"Polygon name.","nullable":true,"type":"string"},"price":{"description":"Price in cents.","type":"integer"},"shippingEstimate":{"description":"Shipping estimate. For instance, \"three business days\" will be represented as `3bd`.","type":"string"},"shippingEstimateDate":{"description":"Shipping estimate date.","nullable":true,"type":"string"},"tax":{"description":"Tax in cents.","type":"integer"},"transitTime":{"description":"Transit time. For instance, \"three business days\" is represented as `3bd`.","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"}},"type":"object"},"quantity":{"description":"Quantity.","type":"integer"},"selectedDeliveryChannel":{"description":"Delivery channel selected by the customer. For example, `\"delivery\"` or `\"pickup-in-point\"`.","nullable":true,"type":"string"},"selectedSla":{"description":"Selected SLA. For example, `\"normal\"` or `\"express\"`.","nullable":true,"type":"string"},"shipsTo":{"description":"List of countries that the item may be shipped to.","items":{},"type":"array"},"slas":{"description":"Information on available SLAs.","items":{"properties":{"availableDeliveryWindows":{"description":"This object contains information about the delivery window available to the shopper.","properties":{"endDateUtc":{"description":"Delivery window ending day and time in UTC.","type":"string"},"lisPrice":{"description":"Delivery window list price.","type":"integer"},"price":{"description":"Delivery window price.","type":"integer"},"startDateUtc":{"description":"Delivery window starting day and time in UTC.","type":"string"},"tax":{"description":"Delivery window tax.","type":"integer"}},"type":"object"},"deliveryChannel":{"description":"Delivery channel.","type":"string"},"deliveryIds":{"description":"Information on each delivery ID.","items":{"properties":{"courierId":{"description":"Courier ID.","type":"string"},"courierName":{"description":"Courier name.","type":"string"},"dockId":{"description":"Warehouse ID.","type":"string"},"quantity":{"description":"Quantity.","type":"integer"},"warehouseId":{"description":"Warehouse ID.","type":"string"}},"type":"object"},"type":"array"},"deliveryWindow":{"description":"In case of scheduled delivery, this object will contain information on the delivery window selected by the shopper.","properties":{"endDateUtc":{"description":"Delivery window ending day and time in UTC.","type":"string"},"lisPrice":{"description":"Delivery window list price.","type":"integer"},"price":{"description":"Delivery window price.","type":"integer"},"startDateUtc":{"description":"Delivery window starting day and time in UTC.","type":"string"},"tax":{"description":"Delivery window tax.","type":"integer"}},"type":"object"},"id":{"description":"SLA ID.","type":"string"},"listPrice":{"description":"List price in cents.","type":"integer"},"lockTTL":{"description":"Estimate date of delivery.","type":"string"},"name":{"description":"SLA name.","type":"string"},"pickupDistance":{"description":"Pickup point distance.","type":"integer"},"pickupPointId":{"description":"Pickup point ID.","nullable":true,"type":"string"},"pickupStoreInfo":{"description":"Information on the pickup store.","properties":{"additionalInfo":{"description":"Additional information.","nullable":true,"type":"string"},"address":{"description":"Address information.","nullable":true,"type":"object"},"dockId":{"description":"Corresponding dock ID.","nullable":true,"type":"string"},"friendlyName":{"description":"Friendly name.","nullable":true,"type":"string"},"isPickupStore":{"description":"Indicates whether it is the pickup store.","type":"boolean"}},"type":"object"},"polygonName":{"description":"Polygon name.","nullable":true,"type":"string"},"price":{"description":"Price in cents.","type":"integer"},"shippingEstimate":{"description":"Shipping estimate. For instance, \"three business days\" will be represented as `3bd`.","type":"string"},"shippingEstimateDate":{"description":"Shipping estimate date.","nullable":true,"type":"string"},"tax":{"description":"Tax in cents.","type":"integer"},"transitTime":{"description":"Transit time. For instance, \"three business days\" is represented as `3bd`.","type":"string"}},"type":"object"},"type":"array"},"subscriptionData":{"description":"Subscription information.","nullable":true,"type":"object"},"totals":{"description":"Information on order totals.","items":{"properties":{"id":{"description":"Total ID.","type":"string"},"name":{"description":"Total name.","type":"string"},"value":{"description":"Total value.","type":"integer"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"marketingData":{"description":"Object containing promotion data such as coupon tracking information and internal or external UTMs.","nullable":true,"type":"object"},"paymentData":{"description":"Payment data information.","properties":{"availableAccounts":{"description":"Available accounts.","items":{},"type":"array"},"availableAssociations":{"description":"Available associations.","type":"object"},"availableTokens":{"description":"Available tokens.","items":{},"type":"array"},"giftCardMessages":{"description":"Array of gift card messages.","items":{},"type":"array"},"giftCards":{"description":"Gift card information, if it applies to the order.","items":{},"type":"array"},"installmentOptions":{"description":"Installment options information.","items":{},"properties":{"bin":{"description":"Bin.","nullable":true,"type":"string"},"installments":{"description":"Installments information.","items":{},"properties":{"count":{"description":"Count information.","type":"integer"},"hasInterestRate":{"description":"Indicates whether the payment has interest.","type":"boolean"},"interestRate":{"description":"Interest rate value.","type":"integer"},"sellerMerchantInstallments":{"description":"Seller merchant installments information.","items":{},"type":"array"},"total":{"description":"Total value of the order without separating cents. For example, $24.99 is represented `2499`.","type":"integer"},"value":{"description":"Value of the order without the interest rate. The value is shown without separating cents.","type":"integer"}},"type":"array"},"paymentGroupName":{"description":"Payment group name.","type":"string"},"paymentName":{"description":"Payment name.","type":"string"},"paymentSystem":{"description":"Payment system identification.","type":"integer"},"value":{"description":"Total value assigned to this payment.","type":"integer"}},"type":"array"},"paymentSystems":{"description":"Information on payment systems.","items":{"properties":{"availablePayments":{"description":"Availability of payment.","nullable":true,"type":"string"},"description":{"description":"Description.","type":"string"},"displayDocument":{"description":"Indicates whether a document is shown.","type":"boolean"},"dueDate":{"description":"Payment due date.","type":"string"},"groupName":{"description":"Payment group name.","type":"string"},"id":{"description":"Payment system ID.","type":"integer"},"isCustom":{"description":"Indicates whether it is custom.","type":"boolean"},"name":{"description":"Payment system name.","type":"string"},"requiresAuthentication":{"description":"Indicates whether a authentication is required.","type":"boolean"},"requiresDocument":{"description":"Indicates whether a document is required.","type":"boolean"},"stringId":{"description":"String ID.","type":"string"},"template":{"description":"Template.","type":"string"},"validator":{"description":"Payment system validator.","nullable":true,"type":"object"}},"type":"object"},"type":"array"},"payments":{"description":"Information on each payment.","items":{},"type":"array"}},"type":"object"},"postalCode":{"description":"Postal Code.","nullable":true,"type":"string"},"ratesAndBenefitsData":{"description":"Information on rates and benefits that apply to the order.","properties":{"rateAndBenefitsIdentifiers":{"description":"List with rates and benefits identifiers.","items":{},"type":"array"},"teaser":{"description":"List with rates and benefits teasers.","items":{},"type":"array"}},"type":"object"},"selectableGifts":{"description":"Array containing the data of the item selected as a gift.","items":{},"type":"array"}},"type":"object"}}},"description":"OK","headers":{}}},"summary":"Fulfillment simulation - External Marketplace","tags":["External Marketplace"]}},"/portal.vtexcommercestable.com.br/api/mkp-category-mapper/categories/marketplace/{id}":{"post":{"deprecated":false,"description":"Mapping categories guarantees that the VTEX category tree has a correct association with the marketplace’s category tree. \n\nTo perform this association, VTEX made VTEX Mapper available. It is a tool integrated to the VTEX platform that allows the user to relate categories created in VTEX to categories from the marketplace. \n\nThis endpoint allows connectors to send the marketplace's category tree mapped in the integration. \n\nConnectors should send the payload compacted in .gzip format. \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).","operationId":"send-category-mapping-vtex-mapper","parameters":[{"description":"Describes the type of the content being sent.","in":"header","name":"Content-Type","required":true,"schema":{"default":"application/json","type":"string"},"style":"simple"},{"description":"HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.","in":"header","name":"Accept","required":true,"schema":{"default":"application/json","type":"string"},"style":"simple"},{"description":"Code identifying returned in the *VTEX Mapper Registration* endpoint.","in":"path","name":"id","required":true,"schema":{"default":"123456789","type":"string"},"style":"simple"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/sendCategoryMappingToVtexMapper"}}},"description":"","required":true},"responses":{"200":{"description":"OK","headers":{}}},"summary":"Send Category Mapping to VTEX Mapper","tags":["External Marketplace"]}},"/portal.vtexcommercestable.com.br/api/mkp-category-mapper/connector/register":{"post":{"deprecated":false,"description":"Mapping categories guarantees that the VTEX category tree has a correct association with the marketplace’s category tree. \n\nTo perform this association, VTEX made VTEX Mapper available. It is a tool integrated to the VTEX platform that allows the user to relate categories created in VTEX to categories from the marketplace. \n\nThis endpoint allows connectors to register the external marketplace integration in VTEX Mapper. \n\nIn case VTEX Mapper detects an error and the call fails, the connector should check if mandatory information was sent correctly. Ex. are URLs correctly registered in the properties categoryTreeEndPoint and mappingEndPoint? \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).","operationId":"vtex-mapper-registration","parameters":[{"description":"Name of the VTEX account. Used as part of the URL.","in":"query","name":"an","required":true,"schema":{"example":"accountName","type":"string"},"style":"form"},{"description":"Describes the type of the content being sent.","in":"header","name":"Content-Type","required":true,"schema":{"default":"application/json","type":"string"},"style":"simple"},{"description":"HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.","in":"header","name":"Accept","required":true,"schema":{"default":"application/json","type":"string"},"style":"simple"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VtexMapperRegistration"}}},"description":"","required":true},"responses":{"200":{"description":"OK","headers":{}}},"summary":"VTEX Mapper Registration","tags":["External Marketplace"]}},"/{accountName}.vtexcommercestable.com.br/api/order-integration/orders":{"post":{"deprecated":false,"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).","operationId":"EnqueueNewOrder","parameters":[{"description":"Describes the type of the content being sent.","in":"header","name":"Content-Type","required":true,"schema":{"default":"application/json","type":"string"},"style":"simple"},{"description":"HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.","in":"header","name":"Accept","required":true,"schema":{"default":"application/json","type":"string"},"style":"simple"},{"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.","explode":true,"in":"query","name":"an","required":false,"schema":{"example":"apiexamples","type":"string"},"style":"form"},{"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.","in":"path","name":"accountName","required":true,"schema":{"default":"apiexamples","type":"string"}},{"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.","explode":true,"in":"query","name":"affiliateId","required":true,"schema":{"example":"MKP","type":"string"},"style":"form"}],"requestBody":{"content":{"application/json":{"example":{"allowFranchises":false,"clientProfileData":{"corporateDocument":null,"corporateName":null,"corporatePhone":null,"document":"99999999999","email":"email@email.com.br","firstName":"John","lastName":"Doe","phone":"99999999999","stateInscription":null,"tradeName":null},"connectorEndpoint":"https://connector-endpoint.com/api/vtex","connectorName":"SkyHub","customData":{"customApps":[{"fields":{"marketplacePaymentMethod":"credit card"},"id":"marketplace-integration","major":1}]},"invoiceData":{"userPaymentInfo":{"paymentMethods":["creditCardPaymentGroup"]}},"items":[{"id":"1","price":975,"quantity":1}],"marketplaceOrderId":"{{$guid}}","marketplaceOrderStatus":"NEW","marketplacePaymentValue":3025,"pickupAccountName":"","shippingData":{"isFob":true,"isMarketplaceFulfillment":true,"logisticsInfo":[{"deliveryIds":{"warehouseId":"AR1"},"lockTTL":"1d","price":2050,"selectedDeliveryChannel":"delivery","selectedSla":"Express","shippingEstimate":"2d"}],"selectedAddresses":[{"addressId":"1","addressType":"Residential","city":"Curitiba","complement":"101","country":"BRA","geoCoordinates":{"latitude":"-29.5","longitude":"-45.8"},"neighborhood":"Portão","number":"4125","postalCode":"81020-235","receiverName":"John Doe","state":"PR","street":"Rua Eduardo Carlos Pereira"}]}},"schema":{"$ref":"#/components/schemas/EnqueueNewOrderRequest"}}},"description":"","required":true},"responses":{"200":{"content":{"application/json":{"example":{"accountName":"grocery1","code":"SOI003","errors":null,"fields":null,"flow":"PlaceOrder","marketplaceOrderId":null,"message":"Order successfully enqueued","operationId":null,"success":true},"schema":{"$ref":"#/components/schemas/Deliverybyseller"}}},"description":"OK","headers":{}},"default":{"content":{"application/json":{"example":{"accountName":"grocery1","code":"SOI003","errors":null,"fields":null,"flow":"PlaceOrder","marketplaceOrderId":null,"message":"Order successfully enqueued","operationId":null,"success":true},"schema":{"$ref":"#/components/schemas/Deliverybyfranchiseseller"}}},"description":"","headers":{}}},"summary":"New Order Integration","tags":["External Marketplace"]}},"/{accountName}.vtexcommercestable.com.br/api/order-integration/orders/status":{"put":{"deprecated":false,"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).","operationId":"UpdateOrderStatus","parameters":[{"description":"Describes the type of the content being sent.","in":"header","name":"Content-Type","required":true,"schema":{"default":"application/json","type":"string"},"style":"simple"},{"description":"HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.","in":"header","name":"Accept","required":true,"schema":{"default":"application/json","type":"string"},"style":"simple"},{"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.","explode":true,"in":"query","name":"an","required":false,"schema":{"example":"apiexamples","type":"string"},"style":"form"},{"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.","in":"path","name":"accountName","required":true,"schema":{"default":"apiexamples","type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"connectorEndpoint":"https://connector-endpoint.com/api/vtex","connectorName":"Skyhub","marketplaceOrderId":"{{$guid}}","marketplaceOrderStatus":"APPROVED"},"schema":{"$ref":"#/components/schemas/UpdateOrderStatusRequest"}}},"description":"","required":true},"responses":{"200":{"content":{"application/json":{"example":{"accountName":null,"code":"SOI003","errors":null,"fields":null,"flow":"ApproveOrder","marketplaceOrderId":"7e62fcd3-827b-400d-be8a-f050a79c4976","message":"Order successfully enqueued","operationId":null,"success":true},"schema":{"$ref":"#/components/schemas/Approveorder"}}},"description":"OK","headers":{}}},"summary":"Update Order Status","tags":["External Marketplace"]}},"/{accountName}.{environment}.com.br/api/fulfillment/pvt/orders":{"post":{"deprecated":false,"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).","operationId":"PlaceFulfillmentOrder","parameters":[{"description":"Name of the VTEX account. Used as part of the URL.","in":"path","name":"accountName","required":true,"schema":{"default":"apiexamples","type":"string"}},{"description":"Environment to be used. It is passed as part of the URL.","in":"path","name":"environment","required":true,"schema":{"default":"vtexcommercestable","type":"string"}},{"description":"Type of the content being sent.","in":"header","name":"Content-Type","required":true,"schema":{"default":"application/json","type":"string"},"style":"simple"},{"description":"HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.","in":"header","name":"Accept","required":true,"schema":{"default":"application/json","type":"string"},"style":"simple"},{"description":"Sales channel.","in":"query","name":"sc","required":false,"schema":{"example":"1","type":"string"},"style":"form"},{"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.","in":"query","name":"affiliateId","required":true,"schema":{"example":"MKP","type":"string"},"style":"form"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"clientProfileData":{"description":"Customer's profile information.","properties":{"corporateDocument":{"description":"Corporate document, if the customer is a legal entity.","example":"12345678000100","nullable":true,"type":"string"},"corporateName":{"description":"Company name, if the customer is a legal entity.","example":"company-name","nullable":true,"type":"string"},"corporatePhone":{"description":"Corporate phone number, if the customer is a legal entity.","example":"+551100988887777","nullable":true,"type":"string"},"document":{"description":"Document informed by the customer. Validation depends on the country.","example":"123456789","type":"string"},"documentType":{"description":"Type of the document informed by the customer.","example":"cpf","type":"string"},"email":{"description":"Customer's email address.","example":"customer@examplemail.com","type":"string"},"firstName":{"description":"Customer's first name.","example":"first-name","type":"string"},"isCorporate":{"description":"`true` if the customer is a legal entity.","example":false,"nullable":true,"type":"boolean"},"lastName":{"description":"Customer's last name.","example":"last-name","type":"string"},"phone":{"description":"Customer's phone number.","example":"+55110988887777","type":"string"},"stateInscription":{"description":"State inscription, if the customer is a legal entity.","example":"12345678","nullable":true,"type":"string"},"tradeName":{"description":"Trade name, if the customer is a legal entity.","example":"trade-name","nullable":true,"type":"string"}},"required":["email","firstName","lastName","documentType","document"],"type":"object"},"isCreatedAsync":{"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/price-divergence-rule--6RlFLhD1rIRRshl83KnCjW#), otherwise the request will not work.","example":false,"type":"boolean"},"items":{"description":"Array of objects containing information on each of the order's items.","items":{"example":{"id":"123456789","quantity":1,"seller":"1"},"properties":{"attachments":{"description":"Array containing information on attachments.","items":{"type":"string"},"type":"array"},"bundleItems":{"description":"Information on services sold along with the SKU. Example: a gift package.","items":{"properties":{"id":{"description":"Service identifier.","example":1034,"type":"integer"},"name":{"description":"Service name.","example":"name-example","type":"string"},"price":{"description":"Service price. The last two digits are the cents.","example":199,"type":"integer"},"type":{"description":"Service type.","example":"type-example","type":"string"}},"type":"object"},"type":"array"},"commission":{"description":"Comission.","example":10,"type":"integer"},"freightCommission":{"description":"Freight comission","example":10,"type":"integer"},"id":{"description":"The SKU ID.","example":"123","type":"string"},"isGift":{"default":false,"description":"Indicates whether the order is a gift.","type":"boolean"},"itemAttachment":{"description":"Item attachment.","properties":{"content":{"description":"Content referring to the customization requested by the customer.","example":"content-example","type":"string"},"name":{"description":"Attachment name.","example":"name-example","type":"string"}},"type":"object"},"measurementUnit":{"description":"SKU measurement unit.","example":"g","type":"string"},"price":{"description":"Item price within the context of the order without separating cents. For example, $24.99 is represented `2499`.","example":2499,"type":"integer"},"priceTags":{"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":{"properties":{"identifier":{"description":"Price tag identifier.","example":"1234abc-5678b-1234c","type":"string"},"isPercentual":{"default":false,"description":"`true` if price tag value is applied through a percentage.","type":"boolean"},"name":{"description":"Price tag name.","example":"discount@name-1234abc-5678b-1234c","type":"string"},"rawValue":{"description":"Price tag value.","example":-12,"type":"integer"},"value":{"description":"Price tag raw value.","example":-1200,"type":"integer"}},"type":"object"},"type":"array"},"quantity":{"description":"The quantity of items of this specific SKU in the cart to be simulated.","example":1,"format":"int32","type":"integer"},"seller":{"description":"The ID of the seller responsible for this SKU. This ID can be found in your VTEX Admin.","example":"1","type":"string"},"unitMultiplier":{"description":"SKU unit multiplier.","example":1,"type":"integer"}},"required":["id","quantity","seller"],"type":"object"},"type":"array"},"marketingData":{"properties":{"utmCampaign":{"description":"UTM campaign","example":"Black friday","type":"string"},"utmMedium":{"description":"UTM medium.","example":"CPC","type":"string"},"utmSource":{"description":"UTM source.","example":"Facebook","type":"string"},"utmiCampaign":{"description":"utmi_campaign (internal utm)","example":"utmi_campaign-exmaple","type":"string"},"utmiPage":{"description":"utmi_page (internal utm)","example":"utmi_page-example","type":"string"},"utmiPart":{"description":"utmi_part (internal utm)","example":"utmi_part-exmaple","type":"string"}},"type":"object"},"marketplaceOrderId":{"description":"ID of the order in the marketplace.","example":"123456789","type":"string"},"marketplacePaymentValue":{"description":"Value of the payment made to the marketplace.","example":100,"type":"integer"},"marketplaceServicesEndpoint":{"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","type":"string"},"openTextField":{"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","type":"string"},"paymentData":{"default":null,"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,"type":"object"},"shippingData":{"description":"Shipping information.","properties":{"address":{"description":"Shipping address.","properties":{"addressId":{"description":"Address ID.","example":"Home","type":"string"},"addressType":{"description":"Type of address. For example, `Residential` or `Pickup`, among others.","example":"residential","type":"string"},"city":{"description":"City of the shipping address.","example":"Rio de Janeiro","type":"string"},"complement":{"description":"Complement to the shipping address in case it applies.","example":"3rd floor","type":"string"},"country":{"description":"Three letter ISO code of the country of the shipping address.","example":"BRA","type":"string"},"geoCoordinates":{"description":"Array with two strings with geocoordinates, first latitude, then longitude.","items":{"example":"00.00000","type":"string"},"type":"array"},"neighborhood":{"description":"Neighborhood of the shipping address.","example":"Botafogo","type":"string"},"number":{"description":"Number of the building, house or apartment in the shipping address.","example":"300","type":"string"},"postalCode":{"description":"Postal Code. Validation depends on the country.","example":"12345000","type":"string"},"receiverName":{"description":"Name of the person who is going to receive the order.","example":"receiver-name","type":"string"},"reference":{"description":"Complement that might help locate the shipping address more precisely in case of delivery.","example":"Grey building","type":"string"},"state":{"description":"State of the shipping address.","example":"Rio de Janeiro","type":"string"},"street":{"description":"Street of the shipping address.","example":"Praia de Botafogo","type":"string"}},"required":["addressType","receiverName","postalCode","city","state","country","street","number"],"type":"object"},"logisticsInfo":{"description":"Array of objects containing logistics information of each item.","items":{"properties":{"deliveryWindow":{"description":"In case of scheduled delivery, this object will contain information on the delivery window selected by the shopper.","properties":{"endDateUtc":{"description":"Delivery window ending day and time in UTC.","example":"2025-08-15T13:51:41.075Z","type":"string"},"lisPrice":{"default":0,"description":"Delivery window list price.","type":"integer"},"price":{"default":0,"description":"Delivery window price.","type":"integer"},"startDateUtc":{"description":"Delivery window starting day and time in UTC.","example":"2025-08-15T13:51:41.075Z","type":"string"},"tax":{"default":0,"description":"Delivery window tax.","type":"integer"}},"type":"object"},"itemIndex":{"description":"Index of the item in the `items` array, starting from 0.","example":0,"type":"integer"},"lockTTL":{"description":"Logistics reservation waiting time.","example":"8d","type":"string"},"price":{"description":"Shipping price for the item. Does not account for the whole order's shipping price.","example":1099,"type":"integer"},"selectedSla":{"description":"Selected shipping option","example":"Express","type":"string"},"shippingEstimate":{"description":"Estimated time until delivery for the item.","example":"7d","type":"string"}},"required":["itemIndex","selectedSla","price"],"type":"object"},"type":"array"},"updateStatus":{"description":"Indicate whether this object's information is up to date according to the order's items. An order can not be placed if `\"outdated\"`","example":"updated","type":"string"}},"type":"object"}},"required":["marketplaceOrderId","marketplaceServicesEndpoint","marketplacePaymentValue","items","clientProfileData","shippingData"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":[{"clientProfileData":{"corporateDocument":null,"corporateName":null,"corporatePhone":null,"document":"11417984642","documentType":"cpf","email":"fba45537f5c84d4092cf064da742fe3d@ct.vtex.com.br","firstName":"Júlio","isCorporate":false,"lastName":"Augusto de Oliveira","phone":"395555258","stateInscription":null,"tradeName":null,"userProfileId":null},"customData":null,"followUpEmail":"9762a2a9028a4b5d8eb9a8ff909d15ce@ct.vtex.com.br","items":[{"bundleItems":[],"comission":0,"freightComission":0,"id":"2","isGift":false,"measurementUnit":"un","price":13890,"priceTable":null,"priceTags":[],"quantity":1,"seller":"1","unitMultiplier":1}],"marketplaceOrderId":"956","orderId":"MBR-956","paymentData":null,"shippingData":{"address":{"addressId":"Casa","addressType":"Residencial","city":"Americana","complement":null,"country":"BRA","geoCoordinates":[],"neighborhood":"Grande circo","number":"31187","postalCode":"98776003","receiverName":"Júlio Augusto de Oliveira","reference":"Bairro do foca / Posto de Saúde 65","state":"SP","street":"Rua da casa"},"isFOB":false,"logisticsInfo":[{"addressId":"Casa","deliveryIds":[{"dockId":"1","warehouseId":11}],"deliveryWindow":null,"itemIndex":0,"lockTTL":"8d","price":1090,"selectedDeliveryChannel":"delivery","selectedSla":"Correios","shippingEstimate":"7d"}],"selectedaddresses":[{"addressId":"Casa","addressType":"Residencial","city":"Americana","complement":null,"country":"BRA","geoCoordinates":[],"neighborhood":"Grande circo","number":"31187","postalCode":"98776003","receiverName":"Júlio Augusto de Oliveira","reference":"Bairro do foca / Posto de Saúde 65","state":"SP","street":"Rua da casa"}],"trackingHints":[]}}]}}}},"description":"OK","headers":{}}},"summary":"Place fulfillment order","tags":["External Marketplace"]}},"/{accountName}.{environment}.com.br/api/fulfillment/pvt/orders/{orderId}/fulfill":{"post":{"deprecated":false,"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).","operationId":"AuthorizeDispatchForFulfillmentOrder","parameters":[{"description":"Name of the VTEX account. Used as part of the URL.","in":"path","name":"accountName","required":true,"schema":{"default":"apiexamples","type":"string"}},{"description":"Environment to be used. It is passed as part of the URL.","in":"path","name":"environment","required":true,"schema":{"default":"vtexcommercestable","type":"string"}},{"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\"`.","in":"path","name":"orderId","required":true,"schema":{"default":"MKP-123","type":"string"}},{"description":"Type of the content being sent.","in":"header","name":"Content-Type","required":true,"schema":{"default":"application/json","type":"string"},"style":"simple"},{"description":"HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.","in":"header","name":"Accept","required":true,"schema":{"default":"application/json","type":"string"},"style":"simple"},{"description":"Sales channel.","in":"query","name":"sc","required":false,"schema":{"example":"1","type":"string"},"style":"form"},{"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.","in":"query","name":"affiliateId","required":true,"schema":{"example":"MKP","type":"string"},"style":"form"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"marketplaceOrderId":{"default":"123","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\"`.","type":"string"}},"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":{"marketplaceOrderId":"123"}}}}},"description":"OK","headers":{}}},"summary":"Authorize dispatch for fulfillment order","tags":["External Marketplace"]}},"/{fulfillmentEndpoint}/pvt/orderForms/simulation":{"post":{"deprecated":false,"description":"This endpoint may be called upon by VTEX for fulfillment simulation in the external seller different contexts. See examples below.\n\nWhen a [price](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/price) or [inventory](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/inventory) notification request returns a response with status `200 OK`, it means that the SKU already exists in the marketplace. Whenever this happens, the marketplace will call the seller to get two updated information about the SKU: Price and Inventory.\n\nThe seller needs to have an endpoint implemented in order to receive this call and send a response containing the requested information to the marketplace. We call it the Fulfillment Simulation endpoint.\n\nIf the seller wishes to include other parameters in this call (like account name, or [sales channel](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV) ID), this should be done within their {fulfillmentEndpoint}. This path is then inserted in the marketplace's VTEX admin when [configuring a seller](https://help.vtex.com/en/tutorial/configurando-seller--tutorials_392). \n\nThe marketplace will send an object containing an array of items. The seller must use this list to get the updated information about the referred SKUs and send them back to the marketplace, following the response format explained in the API Reference. \n\nThis call is also applied in the Storefront simulation scenario, in which case the request from VTEX does not send the paramenters `country` and `postalCode`. \nThe call's payload can be adapted into two scenarios: \n\n- **Displaying items in the storefront**: the address information can be nulled in the request, since they are not mandatory data for this context.   \n- **Making a shopping cart simulation during checkout**: address information must be sent, since this data is needed to calculate freight values. If the address information (including `postalCode` and `country`) is not sent through the call, VTEX interprets the stock balance as zero. Without a valid stock balance, the seller will not be shown as an option during checkout. \n  \n## Request body example - Indexing simulation\n\n```\n{\n    \"items\": [\n      {\n        \"id\": \"7908010136043\",\n        \"quantity\": 1,\n        \"seller\": \"1\",\n      }\n    ],\n    \"isCheckedIn\": false,\n  }\n``` \n## Request body example - Checkout simulation\n\n```\n{\n    \"items\": [\n      {\n        \"id\": \"7908010136043\",\n        \"quantity\": 1,\n        \"seller\": \"1\",\n      }\n    ],\n    \"postalCode\": \"22270-030\",\n    \"country\": \"BRA\",\n  }\n```","operationId":"fulfillment-simulation","parameters":[{"description":"This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.","in":"path","name":"fulfillmentEndpoint","required":true,"schema":{"example":"marketplaceexample.externalseller.com","type":"string"},"style":"simple"},{"description":"HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.","in":"header","name":"Accept","required":true,"schema":{"example":"application/json","type":"string"},"style":"simple"},{"description":"Describes the type of the content being sent.","in":"header","name":"Content-Type","required":true,"schema":{"example":"application/json","type":"string"},"style":"simple"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"country":{"description":"ISO 3-digit code of the country where the delivery address is located.  This field is mandatory, for shopping carts simulations, where both Country and Postal Code are required. This field should be sent as `null` for storefront simulations, where the information is not necessary.","example":"USA","type":"string"},"geoCoordinates":{"description":"Geographic coordinates of the delivery address. This may be used instead of the postalCode, in case the marketplace is configured to accept geolocation. Example of value: `[-22.9443504,-43.1825635]`.","items":{"example":"00.00000000","type":"string"},"type":"array"},"items":{"description":"Array containing the cart items.","items":{"$ref":"#/components/schemas/fulfillmentItem"},"type":"array"},"postalCode":{"description":"Delivery address postal code. This field is mandatory for shopping carts simulations, where both Country and Postal Code are required. This field should be sent as `null` for storefront simulations, where the information is not necessary.","example":"12345678","type":"string"},"sc":{"description":"Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) associated to the seller account created.","example":"1","type":"string"}},"required":["postalCode"],"type":"object"}}},"description":"","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"description":"Expected response body of fulfillment simulation","example":{"country":"BRA","items":[{"id":"2000037","listPrice":67203,"measurementUnit":"un","merchantName":"mySeller1","offerings":[{"id":"5","name":"1 year warranty","price":10000,"type":"Warranty"}],"price":67203,"priceTags":[],"priceValidUntil":"2025-08-15T13:51:41.075Z","quantity":1,"requestIndex":0,"seller":"1","unitMultiplier":1}],"logisticsInfo":[{"deliveryChannels":[{"id":"delivery","stockBalance":179},{"id":"pickup-in-point","stockBalance":20}],"itemIndex":0,"quantity":1,"shipsTo":["BRA"],"slas":[{"availableDeliveryWindows":[{"endDateUtc":"2025-08-15T13:51:41.075Z","price":0,"startDateUtc":"2025-08-15T13:51:41.075Z"}],"deliveryChannel":"pickup-in-point","id":"Curbside pickup","name":"Curbside pickup","pickupStoreInfo":{"additionalInfo":"","address":{"addressId":"548304ed-dd40-4416-b12b-4b32bfa7b1e0","addressType":"pickup","city":"Curitiba","complement":"Loja 10","country":"BRA","geoCoordinates":[49.334934,25.401705],"neighborhood":"Santa Felicidade","number":"100","postalCode":"82320-040","receiverName":"Juliana","reference":"Next to the unicorn statue","state":"PR","street":"Rua Domingos Strapasson"},"friendlyName":"Santa Felicidade","isPickupStore":true},"price":0,"shippingEstimate":"0bd"}],"stockBalance":199}],"postalCode":"80250000"},"properties":{"country":{"description":"ISO 3-digit code of the country where the delivery address is located. If you don’t want to send it, use the value null.","example":"BRA","title":"Country","type":"string"},"items":{"description":"Contains the data about each SKU in the cart.","example":[{"id":"2000037","listPrice":67203,"measurementUnit":"un","merchantName":"mySeller1","offerings":[{"id":"5","name":"1 year warranty","price":10000,"type":"Warranty"}],"price":67203,"priceTags":[],"priceValidUntil":"2025-08-15T13:51:41.075Z","quantity":1,"requestIndex":0,"seller":"1","unitMultiplier":1}],"items":{"description":"Contains the data about each SKU in the cart.","properties":{"id":{"description":"SKU ID","example":"2000037","title":"id","type":"string"},"listPrice":{"description":"List price. It’s the amount presented to the customer as a “previous” price that has been lowered due to a discount. Don’t separate the decimal places. The last two digits are the cents.","example":67203,"title":"listPrice","type":"integer"},"measurementUnit":{"description":"SKU’s measurement unit.","example":"un","title":"measurementUnit","type":"string"},"merchantName":{"description":"Name of the marketplace, used to guide payments. This field should be nulled if the marketplace is responsible for processing payments. Check out our [​​Payments in VTEX marketplaces](https://help.vtex.com/en/tutorial/payments-in-vtex-marketplaces--2kYOfWCZYweJkYl18bw9yD) article to know more.","example":"mySeller1","title":"merchantName","type":"string"},"offerings":{"description":"Services that may be offered for this SKU. example are the assembly of a piece of furniture or warranty. In case these information are sent, the following fields are mandatory. If you don’t want to send it, use an empty array.","example":[{"id":"5","name":"1 year warranty","price":10000,"type":"Warranty"}],"items":{"description":"Services that may be offered for this SKU. example are the assembly of a piece of furniture or warranty. In case these information are sent, the following fields are mandatory. If you don’t want to send it, use an empty array.","properties":{"id":{"description":"Service ID.","example":"5","title":"id","type":"string"},"name":{"description":"Service name.","example":"1 year warranty","title":"name","type":"string"},"price":{"description":"Service price. The last two digits are the cents.","example":10000,"title":"price","type":"integer"},"type":{"description":"Type of the service.","example":"Warranty","title":"type","type":"string"}},"required":["type","id","name","price"],"title":"offerings","type":"object"},"title":"offerings","type":"array"},"price":{"description":"Actual selling price of the SKU. Don’t separate the decimal places. The last two digits are the cents.","example":67203,"title":"price","type":"integer"},"priceTags":{"description":"List with the promotions applied to the SKU.","items":{"description":"Promotions applied to the SKU.","example":"promotion 1","title":"priceTags","type":"string"},"title":"priceTags","type":"array"},"priceValidUntil":{"description":"Expiration date of the SKU price. Example: `2014-03-01T22:58:28.143`. In case you don’t want to send it, use the value null.","example":"2025-08-15T13:51:41.075Z","nullable":true,"title":"priceValidUntil","type":"string"},"quantity":{"default":0,"description":"Quantity of the item. The seller should send the quantity that was indicated in the request, or the maximum quantity possible.","example":1,"title":"quantity","type":"integer"},"requestIndex":{"description":"Position of this item in the original array (request).","example":0,"title":"requestIndex","type":"integer"},"seller":{"description":"ID of the seller as registered in VTEX. You should send the same value that came in the request.","example":"1","title":"seller","type":"string"},"unitMultiplier":{"description":"SKU unit multiplier. The default value is 1.","example":1,"title":"unitMultiplier","type":"integer"}},"required":["id","listPrice","measurementUnit","merchantName","offerings","price","priceTags","priceValidUntil","quantity","requestIndex","seller","unitMultiplier"],"title":"Items","type":"object"},"title":"Items","type":"array"},"logisticsInfo":{"description":"Array that contains the data regarding the delivery methods and stock for each item. If all products are unavailable, this field should return empty.","example":[{"deliveryChannels":[{"id":"delivery","stockBalance":179},{"id":"pickup-in-point","stockBalance":20}],"itemIndex":0,"quantity":1,"shipsTo":["BRA"],"slas":[{"availableDeliveryWindows":[{"endDateUtc":"2025-08-15T13:51:41.075Z","price":0,"startDateUtc":"2025-08-15T13:51:41.075Z"}],"deliveryChannel":"pickup-in-point","id":"Curbside pickup","name":"Curbside pickup","pickupStoreInfo":{"additionalInfo":"","address":{"addressId":"548304ed-dd40-4416-b12b-4b32bfa7b1e0","addressType":"pickup","city":"Curitiba","complement":"Loja 10","country":"BRA","geoCoordinates":[49.334934,25.401705],"neighborhood":"Santa Felicidade","number":"100","postalCode":"82320-040","receiverName":null,"reference":null,"state":"PR","street":"Rua Domingos Strapasson"},"friendlyName":"Santa Felicidade","isPickupStore":true},"price":0,"shippingEstimate":"0bd"}],"stockBalance":199}],"items":{"description":"An explanation about the purpose of this instance.","example":{"deliveryChannels":[{"id":"delivery","stockBalance":179},{"id":"pickup-in-point","stockBalance":20}],"itemIndex":0,"quantity":1,"shipsTo":["BRA"],"slas":[{"availableDeliveryWindows":[{"endDateUtc":"2025-08-15T13:51:41.075Z","price":0,"startDateUtc":"2025-08-15T13:51:41.075Z"}],"deliveryChannel":"pickup-in-point","id":"Curbside pickup","name":"Curbside pickup","pickupStoreInfo":{"additionalInfo":"","address":{"addressId":"548304ed-dd40-4416-b12b-4b32bfa7b1e0","addressType":"pickup","city":"Curitiba","complement":"Loja 10","country":"BRA","geoCoordinates":[49.334934,25.401705],"neighborhood":"Santa Felicidade","number":"100","postalCode":"82320-040","receiverName":null,"reference":null,"state":"PR","street":"Rua Domingos Strapasson"},"friendlyName":"Santa Felicidade","isPickupStore":true},"price":0,"shippingEstimate":"0bd"}],"stockBalance":199},"properties":{"deliveryChannels":{"description":"Array contains the stock balance for each channel.","example":[{"id":"delivery","stockBalance":179},{"id":"pickup-in-point","stockBalance":20}],"items":{"description":"Object containing ID and stockbalance of each delivery channel.","example":{"id":"delivery","stockBalance":179},"properties":{"id":{"description":"Identifies the channel type whose stock balance will be informed in the next field. Possible values are: pickup-in-point for pickup point and delivery for regular delivery.","example":"pickup-in-point","title":"id","type":"string"},"stockBalance":{"description":"Stock balance for the channel type selected in the previous field.","example":20,"title":"stockBalance","type":"integer"}},"required":["id","stockBalance"],"title":"deliveryChannels","type":"object"},"title":"deliveryChannels","type":"array"},"itemIndex":{"description":"Position of this item in the original array, i.e., in the array that came with the request. This index is what identifies which SKU you are referring to for each object inside the logisticsInfo.","example":0,"title":"itemIndex","type":"integer"},"quantity":{"description":"Quantity of the item. The seller should send the quantity that was indicated in the request, or the maximum quantity possible.","example":1,"title":"quantity","type":"integer"},"shipsTo":{"description":"ISO 3-digit code of the countries to where the SKU is delivered.","example":["BRA","BOL"],"items":{"description":"Array of country codes","example":"BRA","title":"shipsTo","type":"string"},"title":"shipsTo","type":"array"},"slas":{"description":"Contains the available delivery methods.","example":[{"availableDeliveryWindows":[{"endDateUtc":"2025-08-15T13:51:41.076Z","price":0,"startDateUtc":"2025-08-15T13:51:41.076Z"}],"deliveryChannel":"pickup-in-point","id":"Curbside pickup","name":"Curbside pickup","pickupStoreInfo":{"additionalInfo":"","address":{"addressId":"548304ed-dd40-4416-b12b-4b32bfa7b1e0","addressType":"pickup","city":"Curitiba","complement":"Loja 10","country":"BRA","geoCoordinates":[49.334934,25.401705],"neighborhood":"Santa Felicidade","number":"100","postalCode":"82320-040","receiverName":"Juliana","reference":"Right next to the Unicorn statue.","state":"PR","street":"Rua Domingos Strapasson"},"friendlyName":"Santa Felicidade","isPickupStore":true},"price":0,"shippingEstimate":"0bd"}],"items":{"description":"Object with delivery methods information.","example":{"availableDeliveryWindows":[{"endDateUtc":"2025-08-15T13:51:41.076Z","price":0,"startDateUtc":"2025-08-15T13:51:41.076Z"}],"deliveryChannel":"pickup-in-point","id":"Curbside pickup","name":"Curbside pickup","pickupStoreInfo":{"additionalInfo":"","address":{"addressId":"548304ed-dd40-4416-b12b-4b32bfa7b1e0","addressType":"pickup","city":"Curitiba","complement":"Loja 10","country":"BRA","geoCoordinates":[49.334934,25.401705],"neighborhood":"Santa Felicidade","number":"100","postalCode":"82320-040","receiverName":"Juliana","reference":"Right next to the Unicorn statue.","state":"PR","street":"Rua Domingos Strapasson"},"friendlyName":"Santa Felicidade","isPickupStore":true},"price":0,"shippingEstimate":"0bd"},"properties":{"availableDeliveryWindows":{"description":"Contains the delivery windows available for the SLA.","example":[{"endDateUtc":"2025-08-15T13:51:41.076Z","price":0,"startDateUtc":"2025-08-15T13:51:41.076Z"},{"endDateUtc":"2025-08-15T13:51:41.076Z","price":100,"startDateUtc":"2025-08-15T13:51:41.076Z"}],"items":{"description":"Object with delivery windows information.","example":{"endDateUtc":"2025-08-15T13:51:41.076Z","price":0,"startDateUtc":"2025-08-15T13:51:41.076Z"},"properties":{"endDateUtc":{"description":"End date of the delivery window.","example":"2025-08-15T13:51:41.076Z","title":"endDateUtc","type":"string"},"price":{"description":"Extra price for scheduled delivery. The last two digits are the cents.","example":0,"title":"price","type":"integer"},"startDateUtc":{"description":"Start date of the delivery window.","example":"2025-08-15T13:51:41.076Z","title":"startDateUtc","type":"string"}},"required":["startDateUtc","endDateUtc","price"],"title":"availableDeliveryWindows","type":"object"},"title":"availableDeliveryWindows","type":"array"},"deliveryChannel":{"description":"Type of delivery channel. The values that are possible are: `pickup-in-point` for pickup point and `delivery` for regular delivery.","example":"pickup-in-point","title":"deliveryChannel","type":"string"},"id":{"description":"Identifier of the delivery method.","example":"Curbside pickup","title":"id","type":"string"},"name":{"description":"Name of the delivery method.","example":"Curbside pickup","title":"name","type":"string"},"pickupStoreInfo":{"description":"Contains the data about the pickup point. If you don’t want to send this, use the value `null`.","example":{"additionalInfo":"","address":{"addressId":"548304ed-dd40-4416-b12b-4b32bfa7b1e0","addressType":"pickup","city":"Curitiba","complement":"Loja 10","country":"BRA","geoCoordinates":[49.334934,25.401705],"neighborhood":"Santa Felicidade","number":"100","postalCode":"82320-040","receiverName":"Juliana","reference":"Right next to the Unicorn statue.","state":"PR","street":"Rua Domingos Strapasson"},"friendlyName":"Santa Felicidade","isPickupStore":true},"nullable":true,"properties":{"additionalInfo":{"description":"Description or extra information about the pickup point.","example":"Pick up your order at the cashier.","title":"additionalInfo","type":"string"},"address":{"description":"Address data of the pickup point.","example":{"addressId":"548304ed-dd40-4416-b12b-4b32bfa7b1e0","addressType":"pickup","city":"Curitiba","complement":"Loja 10","country":"BRA","geoCoordinates":[49.334934,25.401705],"neighborhood":"Santa Felicidade","number":"100","postalCode":"82320-040","receiverName":"Juliana","reference":"Right next to the Unicorn statue.","state":"PR","street":"Rua Domingos Strapasson"},"properties":{"addressId":{"description":"Identifies the pickup point.","example":"548304ed-dd40-4416-b12b-4b32bfa7b1e0","title":"addressId","type":"string"},"addressType":{"description":"The possible value is pickup.","example":"pickup","title":" addressType","type":"string"},"city":{"description":"Pickup point's city.","example":"Rio de Janeiro","title":"city","type":"string"},"complement":{"description":"Complement of the pickup point address.","example":"2nd floor","title":"complement","type":"string"},"country":{"description":"3-digit ISO code of the country where the pickup point is located.","example":"BRA","title":"country","type":"string"},"geoCoordinates":{"description":"Contains the geographic coordinates of the pickup point.","example":[-49.334934,25.401705],"items":{"description":"Contains the geographic coordinates of the pickup point.","example":25.401705,"title":"geoCoordinates","type":"number"},"title":"geoCoordinates","type":"array"},"neighborhood":{"description":"Neighborhood where the pickup point is located.","example":"Botafogo","title":"neighborhood","type":"string"},"number":{"description":"Address number of the pickup point.","example":"100","title":"number","type":"string"},"postalCode":{"description":"Postal code of the pickup point. This field is mandatory, for shopping carts simulations, where both Country and Postal Code are required. This field should be sent as `null` for storefront simulations, where the information is not necessary.","example":"82320-040","title":"postalCode","type":"string"},"receiverName":{"description":"Name of the person who will receive the product. May be sent as `null`.","example":"Juliana","nullable":true,"title":"receiverName","type":"string"},"reference":{"description":"A reference for the pickup point address. ","example":"Right next to the Unicorn statue.","nullable":true,"title":"reference","type":"string"},"state":{"description":"Pickup point's state.","example":"RJ","title":"state","type":"string"},"street":{"description":"Street where the pickup point is located.","example":"Rua Praia de Botafogo","title":"street","type":"string"}},"required":["addressType","receiverName","addressId","postalCode","city","state","country","street","number","neighborhood","complement","reference","geoCoordinates"],"title":"address","type":"object"},"friendlyName":{"description":"Friendly name of the pickup point.","example":"Store ABC","title":"friendlyName","type":"string"},"isPickupStore":{"description":"`true` if it is a pickup point.","example":true,"title":"isPickupStore","type":"boolean"}},"required":["isPickupStore","friendlyName","address","additionalInfo"],"title":"pickupStoreInfo","type":"object"},"price":{"description":"Delivery price. The two last digits are the cents.","example":846,"title":"price","type":"integer"},"shippingEstimate":{"description":"Time estimated for the delivery. Possible suffixes are `bd` for *business day* , `h` for *hours*, and `m` for *minutes*.","example":"19bd","title":"shippingEstimate","type":"string"}},"required":["id","deliveryChannel","name","price","shippingEstimate","availableDeliveryWindows","pickupStoreInfo"],"title":"slas","type":"object"},"title":"slas","type":"array"},"stockBalance":{"description":"Stock balance of the SKU.","example":199,"title":"stockBalance","type":"integer"}},"required":["itemIndex","quantity","shipsTo","slas","stockBalance","deliveryChannels"],"title":"A Schema","type":"object"},"title":"logisticsInfo","type":"array"},"postalCode":{"description":"Postal code of the delivery address. This field is mandatory, for shopping carts simulations, where both Country and Postal Code are required. This field should be sent as `null` for storefront simulations, where the information is not necessary.","example":"80250000","title":"postalCode","type":"string"}},"required":["country","items","logisticsInfo","postalCode"],"title":"Response body","type":"object"}}},"description":"OK","headers":{}}},"summary":"Fulfillment simulation - External Seller","tags":["External Seller"]}},"/{fulfillmentEndpoint}/pvt/orders":{"post":{"description":"This request is sent by VTEX to the external seller once the customer finishes their checkout, to let the seller know there is a newly placed order. It does that by calling the **Order Placement** endpoint, which needs to be implemented by the seller.\n\nThe marketplace will send information such as the items contained in the cart, the client’s profile data, the shipping data, and the payment data. With all that, the seller will be able to create the order in their own store.","operationId":"order-placement","parameters":[{"description":"This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.","in":"path","name":"fulfillmentEndpoint","required":true,"schema":{"example":"https://marketplaceexample.externalseller.com","type":"string"},"style":"simple"},{"description":"Length of the request body.","in":"header","name":"content-length","required":true,"schema":{"example":"2183","type":"string"},"style":"simple"},{"description":"Indicates authorization.","in":"header","name":"authorization","required":true,"schema":{"example":"VTEX key=\"appKey\" token=\"appToken\"","type":"string"},"style":"simple"},{"description":"VTEX API app key.","in":"header","name":"x-vtex-api-appkey","required":true,"schema":{"example":"appKey","type":"string"},"style":"simple"},{"description":"VTEX API app token.","in":"header","name":"x-vtex-api-apptoken","required":true,"schema":{"example":"appToken","type":"string"},"style":"simple"},{"description":"HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.","in":"header","name":"accept","required":true,"schema":{"example":"application/json","type":"string"},"style":"simple"},{"description":"Indicates the types of response enconding the client can understand.","in":"header","name":"accept-enconding","required":true,"schema":{"example":"gzip, deflate","type":"string"},"style":"simple"},{"description":"VTEX operation ID.","in":"header","name":"x-vtex-operation-id","required":true,"schema":{"example":"8032114b-63e9-4e64-b30c-f7afcf676d7a","type":"string"},"style":"simple"},{"description":"Determines the protocol used by the client in the request.","in":"header","name":"x-forwarded-proto","required":true,"schema":{"example":"https","type":"string"},"style":"simple"},{"description":"Identifies the originating IP address of the HTTP client.","in":"header","name":"x-forwarded-for","required":true,"schema":{"example":"179.35.30.186, 130.176.35.67, 172.16.247.49","type":"string"},"style":"simple"},{"description":"VTEX cache client bypass.","in":"header","name":"x-vtex-cache-client-bypass","required":true,"schema":{"example":"1","type":"string"},"style":"simple"},{"description":"Describes the type of the content being sent.","in":"header","name":"content-type","required":true,"schema":{"example":"application/json","type":"string"},"style":"simple"},{"description":"Identifies the incoming request in a tracing system.","in":"header","name":"traceparent","required":true,"schema":{"example":"00-083c0ca18bc8d94183f333809a70cd64-bf5e9a641e230540-00","type":"string"},"style":"simple"}],"requestBody":{"content":{"application/json":{"example":{},"schema":{"$ref":"#/components/schemas/orderPlacement"}}},"description":"","required":true},"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":{"clientProfileData":{"corporateDocument":null,"corporateName":null,"corporatePhone":null,"document":"3244239851","documentType":null,"email":"32172239852@gmail.com.br","firstName":"John","isCorporate":false,"lastName":"Smith","phone":"399271258","stateInscription":null,"tradeName":null,"userProfileId":null},"items":[{"Seller":"1","attachments":[],"bundleItems":[],"commission":0,"freightCommission":0,"id":"2002495","isGift":false,"itemAttachment":{"content":{},"name":null},"measurementUnit":null,"price":9990,"priceTags":[],"quantity":1,"unitMultiplier":0}],"marketingData":{"utmCampaign":"freeshipping","utmMedium":"","utmSource":"buscape","utmiCampaign":"artscase for iphone 5","utmiPage":"_","utmiPart":"BuscaFullText"},"marketplaceOrderId":"959311095","marketplacePaymentValue":11080,"marketplaceServicesEndpoint":"https://marketplaceservicesendpoint/","openTextField":null,"paymentData":null,"shippingData":{"address":{"addressId":"Home","addressType":"Residencial","city":"Americana","complement":null,"country":"BRA","geoCoordinates":[],"neighborhood":"SÃO JOSÉ","number":"311","postalCode":"13476103","receiverName":"John Smith","reference":"Bairro Praia Azul / Posto de Saúde 17","state":"SP","street":"JOÃO DAMÁZIO GOMES"},"logisticsInfo":[{"deliveryWindow":null,"itemIndex":0,"lockTTL":"8d","price":1090,"selectedSla":"Regular","shippingEstimate":"7d"}],"updateStatus":"updated"}}}}}},"description":"OK","headers":{}}},"summary":"Order placement","tags":["External Seller"]}},"/{fulfillmentEndpoint}/pvt/orders/{orderId}/cancel":{"post":{"description":"This request may be sent from VTEX to the external seller in case of order cancelation. For that, the seller will need to implement the Marketplace order cancellation endpoint. Whenever this request is received by the seler, the order should be canceled and the fulfillment flow should not proceed. \n\nFor the seller to: \n\n- **Evaluate a cancellation request:** it is possible to send an empty body as a response to the cancellation request, meaning that the seller is evaluating whether to proceed with the cancellation or not. \n\n- **Confirm the cancellation request:** it is possible to confirm the order cancellation by the marketplace by responding to the call with a body including only one information: the `marketplaceOrderId`, which identifies the order in the marketplace. The seller should use this ID to trigger the cancellation of the corresponding order. The seller should then respond with the same `marketplaceOrderId` and also with the `orderId`, which identifies the order in the seller, the date and time of the notification receipt, and a protocol code that confirms the receipt of the request (which may have the value `null`). \n\n- **Refuse a cancellation request:** it is possible to to [send the Invoice](https://developers.vtex.com/vtex-rest-api/reference/external-seller#send-invoice), meaning that the cancellation has been denied, and the flow continues to the [Order Invoicing](https://developers.vtex.com/vtex-rest-api/docs/external-seller-integration-connector#order-invoicing) step, and the ones that follow it. \n\nThis call should be made twice: once for the *Evaluate cancellation request* scenario, and a second time to *Confirm cancellation* or *Refuse cancellation*.","operationId":"mkp-order-cancellation","parameters":[{"description":"This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.","in":"path","name":"fulfillmentEndpoint","required":true,"schema":{"example":"marketplaceexample.externalseller.com","type":"string"},"style":"simple"},{"description":"HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.","in":"header","name":"Accept","required":true,"schema":{"example":"application/json","type":"string"},"style":"simple"},{"description":"Describes the type of the content being sent.","in":"header","name":"Content-Type","required":true,"schema":{"example":"application/json","type":"string"},"style":"simple"},{"description":"ID of the order being fulfilled","in":"path","name":"orderId","required":true,"schema":{"default":"1138342255777-01","type":"string"},"style":"simple"}],"requestBody":{"content":{"application/json":{"example":{"marketplaceOrderId":"1138342255777-01"},"schema":{"properties":{"marketplaceOrderId":{"default":"1138342255777-01","description":"Identifies the order. The seller should use this ID to trigger the cancellation of the corresponding order.","type":"string"}},"required":["marketplaceOrderId"],"type":"object"}}},"description":"","required":true},"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":{"date":"2025-08-15T13:51:41.076Z","marketplaceOrderId":"959311095","orderId":"1138342255777-01","receipt":"e39d05f9-0c54-4469-a626-8bb5cff169f8"}}}}},"description":"OK","headers":{}}},"summary":"Marketplace order cancellation","tags":["External Seller"]}},"/{fulfillmentEndpoint}/pvt/orders/{sellerOrderId}/fulfill":{"post":{"description":"This request is sent from VTEX to the seller after the payment is approved, to notify them that the fulfillment process can start.","operationId":"authorize-fulfillment","parameters":[{"description":"This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.","in":"path","name":"fulfillmentEndpoint","required":true,"schema":{"example":"https://marketplaceexample.externalseller.com","type":"string"},"style":"simple"},{"description":"HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.","in":"header","name":"Accept","required":true,"schema":{"example":"application/json","type":"string"},"style":"simple"},{"description":"Describes the type of the content being sent.","in":"header","name":"Content-Type","required":true,"schema":{"default":"application/json","type":"string"},"style":"simple"},{"description":"Seller's order ID of the order ready for fulfillment. The seller can be a VTEX seller or an external one.","example":"00-1268540501456-01","in":"path","name":"sellerOrderId","required":true,"schema":{"example":"00-1268540501456-01","type":"string"},"style":"simple"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"marketplaceOrderId":{"description":"Identifies the order. The seller should use this ID to trigger the fulfillment process of the corresponding order.","example":"1138342255777-01","type":"string"}},"required":["marketplaceOrderId"],"type":"object"}}},"description":"","required":true},"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":{"date":"2025-08-15T13:51:41.076Z","marketplaceOrderId":"959311095","orderId":"1138342255777-01","receipt":"e39d05f9-0c54-4469-a626-8bb5cff169f8"}}}}},"description":"OK","headers":{}}},"summary":"Authorize fulfillment","tags":["External Seller"]}},"/{marketplaceServicesEndpoint}/pvt/orders/{marketplaceOrderId}/cancel":{"post":{"deprecated":false,"description":"This request is sent by the external seller to the VTEX marketplace to cancel an order.","operationId":"cancel-order-in-marketplace","parameters":[{"description":"This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).","in":"path","name":"marketplaceServicesEndpoint","required":true,"schema":{"example":"marketplaceservicesendpoint.myvtex.com","type":"string"},"style":"simple"},{"description":"Identifies the order in the marketplace.","in":"path","name":"marketplaceOrderId","required":true,"schema":{"example":"1138342255777-01","type":"string"},"style":"simple"},{"description":"HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.","in":"header","name":"Accept","required":true,"schema":{"example":"application/json","type":"string"},"style":"simple"},{"description":"Describes the type of the content being sent.","in":"header","name":"Content-Type","required":true,"schema":{"example":"application/json","type":"string"},"style":"simple"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"reason":{"description":"Insert here the reason for the order's cancellation.","example":"Product is unavailable","type":"string"}},"required":["reason"],"type":"object"}}},"description":"","required":true},"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":{"date":"2025-08-15T13:51:41.076Z","orderId":"1138342255777-01","receipt":"527b1ae251264ef1b7a9b597cd8f16b9"}}}}},"description":"OK","headers":{}}},"summary":"Cancel order in marketplace","tags":["External Seller"]}},"/{marketplaceServicesEndpoint}/pvt/orders/{marketplaceOrderId}/invoice":{"post":{"deprecated":false,"description":"This request is sent by the external seller to the VTEX marketplace to send invoice information.\n\nThis can be necessary in a regular order or in the case of a return. The `type` field is used to indicate which of these is the case.","operationId":"send-invoice","parameters":[{"description":"This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).","in":"path","name":"marketplaceServicesEndpoint","required":true,"schema":{"example":"marketplaceservicesendpoint.myvtex.com","type":"string"},"style":"simple"},{"description":"Identifies the order in the marketplace.","in":"path","name":"marketplaceOrderId","required":true,"schema":{"example":"1138342255777-01","type":"string"},"style":"simple"},{"description":"HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.","in":"header","name":"Accept","required":true,"schema":{"example":"application/json","type":"string"},"style":"simple"},{"description":"Describes the type of the content being sent.","in":"header","name":"Content-Type","required":true,"schema":{"example":"application/json","type":"string"},"style":"simple"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"courier":{"description":"Courier, if available on invoice.","example":"courier-example","type":"string"},"invoiceNumber":{"description":"Invoice number","example":"NFe-00002","type":"string"},"invoiceValue":{"description":"Invoice value.","example":6000,"type":"integer"},"issuanceDate":{"description":"Issuance date.","example":"2025-08-15T13:51:41.076Z","type":"string"},"items":{"description":"Array containing the order items.","items":{"description":"","properties":{"id":{"description":"SKU ID.","example":"6","type":"string"},"price":{"description":"Price of the item.","example":5500,"type":"integer"},"quantity":{"description":"Quantity of items of the SKU in the cart.","example":1,"type":"integer"}},"required":["id","quantity","price"],"type":"object"},"type":"array"},"trackingNumber":{"description":"Tracking number.","example":"12345678abc","type":"string"},"trackingUrl":{"description":"Tracking URL.","example":"https://courier-example.com/tracking","type":"string"},"type":{"description":"Indicates the type of the invoice. Use `\"Output\"` for regular orders and `\"Input\"` for returns.","example":"Output","type":"string"}},"required":["type","invoiceNumber","items"],"type":"object"}}},"description":"","required":true},"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":{"date":"2025-08-15T13:51:41.076Z","orderId":"1138342255777-01","receipt":"527b1ae251264ef1b7a9b597cd8f16b9"}}}}},"description":"OK","headers":{}}},"summary":"Send invoice","tags":["External Seller"]}},"/{marketplaceServicesEndpoint}/pvt/orders/{marketplaceOrderId}/invoice/{invoiceNumber}":{"post":{"deprecated":false,"description":"This request is sent by the external seller to the VTEX marketplace to add tracking information to a given order's invoice, in case it is necessary to do so after the invoice has been sent.","operationId":"send-tracking-information","parameters":[{"description":"This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).","in":"path","name":"marketplaceServicesEndpoint","required":true,"schema":{"example":"marketplaceservicesendpoint.myvtex.com","type":"string"},"style":"simple"},{"description":"Identifies the order in the marketplace.","in":"path","name":"marketplaceOrderId","required":true,"schema":{"example":"1138342255777-01","type":"string"},"style":"simple"},{"description":"Invoice number.","in":"path","name":"invoiceNumber","required":true,"schema":{"example":"NFe-00002","type":"string"},"style":"simple"},{"description":"HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.","in":"header","name":"Accept","required":true,"schema":{"example":"application/json","type":"string"},"style":"simple"},{"description":"Describes the type of the content being sent.","in":"header","name":"Content-Type","required":true,"schema":{"example":"application/json","type":"string"},"style":"simple"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"courier":{"description":"Courier.","example":"courier-example","type":"string"},"dispatchedDate":{"description":"Date of order dispatch.","example":"2025-08-15T13:51:41.076Z","type":"string"},"trackingNumber":{"description":"Tracking number.","example":"12345678abc","type":"string"},"trackingUrl":{"description":"Tracking URL.","example":"https://courier-example.com/tracking","type":"string"}},"type":"object"}}},"description":"","required":true},"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":{"date":"2025-08-15T13:51:41.076Z","orderId":"1138342255777-01","receipt":"527b1ae251264ef1b7a9b597cd8f16b9"}}}}},"description":"OK","headers":{}}},"summary":"Send tracking information","tags":["External Seller"]}},"/{marketplaceServicesEndpoint}/pvt/orders/{marketplaceOrderId}/invoice/{invoiceNumber}/tracking":{"post":{"deprecated":false,"description":"This request is sent by the external seller to the VTEX marketplace to update a given order's tracking status.","operationId":"update-tracking-status","parameters":[{"description":"This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).","in":"path","name":"marketplaceServicesEndpoint","required":true,"schema":{"example":"marketplaceservicesendpoint.myvtex.com","type":"string"},"style":"simple"},{"description":"Identifies the order in the marketplace.","in":"path","name":"marketplaceOrderId","required":true,"schema":{"example":"1138342255777-01","type":"string"},"style":"simple"},{"description":"Invoice number.","in":"path","name":"invoiceNumber","required":true,"schema":{"example":"NFe-00002","type":"string"},"style":"simple"},{"description":"HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.","in":"header","name":"Accept","required":true,"schema":{"example":"application/json","type":"string"},"style":"simple"},{"description":"Describes the type of the content being sent.","in":"header","name":"Content-Type","required":true,"schema":{"example":"application/json","type":"string"},"style":"simple"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"events":{"description":"Array containing information on each tracking event received.","items":{"properties":{"city":{"description":"City where the event ocurred.","example":"Rio de Janeiro","type":"string"},"date":{"description":"Date when event ocurred.","example":"2025-08-15T13:51:41.076Z","type":"string"},"description":{"description":"Description of the event.","example":"Order delivered.","type":"string"},"state":{"description":"State where the event ocurred.","example":"Rio de Janeiro","type":"string"}},"type":"object"},"type":"array"},"isDelivered":{"description":"Indicates if order has been delivered. `false` if it is in transit.","example":true,"type":"boolean"}},"required":["isDelivered"],"type":"object"}}},"description":"","required":true},"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":{"date":"2025-08-15T13:51:41.076Z","orderId":"1138342255777-01","receipt":"527b1ae251264ef1b7a9b597cd8f16b9"}}}}},"description":"OK","headers":{}}},"summary":"Update tracking status","tags":["External Seller"]}}},"components":{"schemas":{"Approveorder":{"example":{"accountName":null,"code":"SOI003","errors":null,"fields":null,"flow":"ApproveOrder","marketplaceOrderId":"7e62fcd3-827b-400d-be8a-f050a79c4976","message":"Order successfully enqueued","operationId":null,"success":true},"properties":{"accountName":{"description":"String that indicates which account made the request.","example":"accountName","nullable":true,"type":"string"},"code":{"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","type":"string"},"errors":{"description":"List with errors related to the response, if there is any.","items":{"example":{"code":"FMT005","description":"Message describing the error.","source":"Fulfillment"},"properties":{"code":{"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","title":"code","type":"string"},"description":{"description":"String containing the error message/description returned by the source.","example":"Message describing the error.","title":"description","type":"string"},"source":{"description":"Includes the following fields pointing out the context of the error: \n\n`Fulfillment` \n\n`Checkout` \n\n`Order Integration`","example":"Fulfillment","title":"Checkout","type":"string"}},"required":["source","code","description"],"title":"errors","type":"object"},"nullable":true,"type":"array"},"fields":{"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.","example":{"franchiseOrderId":"38475934875"},"nullable":true,"properties":{"fields":{"example":{"franchiseOrderId":"432874921387409182347","mainOrderId":"MKP-123456789"},"properties":{"franchiseOrderId":{"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","title":"The franchiseOrderId Schema","type":"string"},"mainOrderId":{"description":"String with the order’s ID inside the main seller account in VTEX.","example":"MKP-123456789","title":"The mainOrderId Schema","type":"string"}},"required":["mainOrderId"],"title":"fields","type":"object"}},"type":"object"},"flow":{"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","type":"string"},"marketplaceOrderId":{"description":"String that indicates the order's ID in the marketplace.","example":"7e62fcd3-827b-400d-be8a-f050a79c4976","nullable":true,"type":"string"},"message":{"description":"String with a message explaining the code returned in the response.","example":"The order was integrated into VTEX successfully","type":"string"},"operationId":{"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","nullable":true,"type":"string"},"success":{"description":"Boolean that indicates if the response is successful or not.","example":true,"type":"boolean"}},"required":["marketplaceOrderId","accountName","code","flow","success","operationId","errors","fields","message"],"title":"Approveorder","type":"object"},"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`).","properties":{"corporateDocument":{"description":"String with the company’s document number, in case of corporate orders.","example":"99999999999","nullable":true,"title":"corporateDocument","type":"string"},"corporateName":{"description":"String with the company’s name, in case of corporate orders.","example":"The Witcher Inc.","nullable":true,"title":"corporateName","type":"string"},"corporatePhone":{"description":"String with the company’s phone number, in case of corporate orders.","example":"99999999999","nullable":true,"title":"corporatePhone","type":"string"},"document":{"description":"String with the customer’s document number.","example":"99999999999","title":"The document schema","type":"string"},"email":{"description":"String with the customer's email.","example":"cirilla@cintra.com","title":"email","type":"string"},"firstName":{"description":"String with the customer's first name.","example":"Cirilla","title":"firstName","type":"string"},"lastName":{"description":"String with the customer’s surname.","example":"Cintra","title":"lastName","type":"string"},"phone":{"description":"String with the customer’s phone number.","example":"99999999999","title":"phone","type":"string"},"stateInscription":{"description":"String with the company’s state registration, in case of corporate orders.","example":"99999999999","nullable":true,"title":"stateInscription","type":"string"},"tradeName":{"description":"String with the company’s fantasy name, in case of corporate orders.","example":"The Witcher","nullable":true,"title":"tradeName","type":"string"}},"required":["email","firstName","lastName","phone","document","corporateDocument","corporatePhone","corporateName","tradeName","stateInscription"],"title":"ClientProfileData","type":"object"},"CustomApp":{"example":{"fields":{"marketplacePaymentMethod":"credit card"},"id":"marketplace-integration","major":1},"properties":{"fields":{"$ref":"#/components/schemas/Fields"},"id":{"description":"App's ID.","example":"ID","title":"id","type":"string"},"major":{"description":"Integer with the major version of the app. Optional, defaulting to one.","example":1,"title":"major","type":"integer"}},"required":["id","major","fields"],"title":"CustomApp","type":"object"},"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).","example":{"customApps":[{"fields":{"marketplacePaymentMethod":"credit card"},"id":"marketplace-integration","major":1}]},"properties":{"customApps":{"description":"","items":{"$ref":"#/components/schemas/CustomApp"},"type":"array"}},"required":["customApps"],"title":"CustomData","type":"object"},"DeliveryIds":{"description":"List of delivery IDs, used for orders where the marketplace is responsible for the fulfillment of the order, including keeping inventory at a warehouse as well as the delivery.","example":{"warehouseId":"AR1"},"properties":{"warehouseId":{"description":"String with the ID of the warehouse used for marketplace fulfillment. Required when `isFob` = `true` and `isMarketplaceFulfillment` = `true`.","example":"AR1","type":"string"}},"required":["warehouseId"],"title":"DeliveryIds","type":"object"},"Deliverybyfranchiseseller":{"example":{"accountName":"grocery1","code":"SOI003","errors":null,"fields":null,"flow":"PlaceOrder","marketplaceOrderId":null,"message":"Order successfully enqueued","operationId":null,"success":true},"properties":{"accountName":{"description":"String that indicates which account made the request.","example":"accountName","type":"string"},"code":{"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","type":"string"},"errors":{"description":"List with errors related to the response, if there's any.","items":{"example":{"code":"FMT005","description":"Message describing the error.","source":"Fulfillment"},"properties":{"code":{"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","title":"code","type":"string"},"description":{"description":"String containing the error message/description returned by the source.","example":"Message describing the error.","title":"description","type":"string"},"source":{"description":"Includes the following fields pointing out the context of the error: \n\n`Fulfillment` \n\n`Checkout` \n\n`Order Integration`","example":"Fulfillment","title":"Checkout","type":"string"}},"required":["source","code","description"],"title":"errors","type":"object"},"nullable":true,"type":"array"},"fields":{"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.","example":{"franchiseOrderId":"38475934875"},"nullable":true,"properties":{"fields":{"example":{"franchiseOrderId":"432874921387409182347","mainOrderId":"MKP-123456789"},"properties":{"franchiseOrderId":{"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","title":"franchiseOrderId","type":"string"},"mainOrderId":{"description":"String with the order’s ID inside the main seller account in VTEX.","example":"MKP-123456789","title":"mainOrderId","type":"string"}},"required":["mainOrderId"],"title":"fields","type":"object"}},"type":"object"},"flow":{"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","type":"string"},"marketplaceOrderId":{"description":"String that indicates the order's ID in the marketplace.","example":"7e62fcd3-827b-400d-be8a-f050a79c4976","nullable":true,"type":"string"},"message":{"description":"String with a message explaining the code returned in the response. ","example":"The order was integrated into VTEX successfully","nullable":true,"type":"string"},"operationId":{"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","nullable":true,"type":"string"},"success":{"description":"Boolean that indicates if the response is successful or not.","example":true,"type":"boolean"}},"required":["marketplaceOrderId","accountName","code","flow","success","operationId","errors","fields","message"],"title":"Deliverybyfranchiseseller","type":"object"},"Deliverybyseller":{"example":{"accountName":"grocery1","code":"SOI003","errors":null,"fields":null,"flow":"PlaceOrder","marketplaceOrderId":null,"message":"Order successfully enqueued","operationId":null,"success":true},"properties":{"accountName":{"description":"String that indicates which account made the request.","example":"accountName","type":"string"},"code":{"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","type":"string"},"errors":{"description":"List with errors related to the response, if there's any.","items":{"example":{"code":"FMT005","description":"Message describing the error.","source":"Fulfillment"},"properties":{"code":{"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","title":"code","type":"string"},"description":{"description":"String containing the error message/description returned by the source.","example":"Message describing the error.","title":"description","type":"string"},"source":{"description":"Includes the following fields pointing out the context of the error: \n\n`Fulfillment` \n\n`Checkout` \n\n`Order Integration`","example":"Fulfillment","title":"Checkout","type":"string"}},"required":["source","code","description"],"title":"errors","type":"object"},"nullable":true,"type":"array"},"fields":{"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.","example":{"franchiseOrderId":"38475934875"},"nullable":true,"properties":{"fields":{"example":{"franchiseOrderId":"432874921387409182347","mainOrderId":"MKP-123456789"},"properties":{"franchiseOrderId":{"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","title":"franchiseOrderId","type":"string"},"mainOrderId":{"description":"String with the order’s ID inside the main seller account in VTEX.","example":"MKP-123456789","title":"mainOrderId","type":"string"}},"required":["mainOrderId"],"title":"fields","type":"object"}},"type":"object"},"flow":{"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","type":"string"},"marketplaceOrderId":{"description":"String that indicates the order's ID in the marketplace.","example":"7e62fcd3-827b-400d-be8a-f050a79c4976","nullable":true,"type":"string"},"message":{"description":"String with a message explaining the code returned in the response. ","example":"The order was integrated into VTEX successfully","type":"string"},"operationId":{"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","nullable":true,"type":"string"},"success":{"description":"Boolean that indicates if the response is successful or not.","example":true,"type":"boolean"}},"required":["marketplaceOrderId","accountName","code","flow","success","operationId","errors","fields","message"],"title":"Deliverybyseller","type":"object"},"EnqueueNewOrderRequest":{"example":{"allowFranchises":false,"clientProfileData":{"corporateDocument":null,"corporateName":null,"corporatePhone":null,"document":"99999999999","email":"email@email.com.br","firstName":"John","lastName":"Doe","phone":"99999999999","stateInscription":null,"tradeName":null},"connectorEndpoint":"https://connector-endpoint.com/api/vtex","connectorName":"SkyHub","customData":{"customApps":[{"fields":{"marketplacePaymentMethod":"credit card"},"id":"marketplace-integration","major":1}]},"invoiceData":{"userPaymentInfo":{"paymentMethods":["creditCardPaymentGroup"]}},"items":[{"id":"1","price":975,"quantity":1}],"marketplaceOrderId":"{{$guid}}","marketplaceOrderStatus":"NEW","marketplacePaymentValue":3025,"pickupAccountName":"","shippingData":{"isFob":true,"isMarketplaceFulfillment":true,"logisticsInfo":[{"deliveryIds":{"warehouseId":"AR1"},"lockTTL":"1d","price":2050,"selectedDeliveryChannel":"delivery","selectedSla":"Express","shippingEstimate":"2d"}],"selectedAddresses":[{"addressId":"1","addressType":"Residential","city":"Curitiba","complement":"101","country":"BRA","geoCoordinates":{"latitude":"-29.5","longitude":"-45.8"},"neighborhood":"Portão","number":"4125","postalCode":"81020-235","receiverName":"John Doe","state":"PR","street":"Rua Eduardo Carlos Pereira"}]}},"properties":{"allowFranchises":{"description":"Boolean indicating whether franchise accounts linked to the main seller should be considered. That is, if the order delivery pickup/SLA can belong to a [franchise account](https://help.vtex.com/en/tutorial/what-is-a-franchise-account--kWQC6RkFSCUFGgY5gSjdl), for example. This field is optional and defaults to `false`.","example":false,"title":"allowFranchises","type":"boolean"},"clientProfileData":{"$ref":"#/components/schemas/ClientProfileData"},"connectorEndpoint":{"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 accepts 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","title":"connectorEndpoint","type":"string"},"connectorName":{"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","title":"connectorName","type":"string"},"customData":{"$ref":"#/components/schemas/CustomData"},"invoiceData":{"$ref":"#/components/schemas/InvoiceData"},"items":{"items":{"$ref":"#/components/schemas/Item"},"type":"array"},"marketplaceOrderId":{"description":"String that indicates the order's ID in the marketplace.","example":"7e62fcd3-827b-400d-be8a-f050a79c4976","title":"marketplaceOrderId","type":"string"},"marketplaceOrderStatus":{"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 it’s status in VTEX after integrating it. This field accepts the following values:  \n\n- `new`  \n\n- `approved`","example":"new","title":"marketplaceOrderStatus","type":"string"},"marketplacePaymentValue":{"description":"Integer that indicates the order’s total value, which the marketplace will pay to the seller. It’s important to note that this value should include interest, if that’s the case. If the value is `USD110.50`, convert it to the format → `11050`.","example":11050,"title":"marketplacePaymentValue","type":"integer"},"pickupAccountName":{"description":"String that indicates the name of the account responsible for the order’s pickup point. It is only required for pickup-in-point orders from franchise accounts, when franchise accounts `allowFranchises` is `true` and the order in question has a `pickup-in-point` delivery type. It is optional otherwise.","example":"accountName","title":"pickupAccountName","type":"string"},"shippingData":{"$ref":"#/components/schemas/ShippingData"}},"required":["marketplaceOrderId","marketplaceOrderStatus","marketplacePaymentValue","allowFranchises","items","clientProfileData","shippingData","invoiceData"],"title":"EnqueueNewOrderRequest","type":"object"},"Fields":{"description":"String dictionary with the names of the fields and their respective values that must be inserted into the order.","example":{"marketplacePaymentMethod":"credit card"},"properties":{"marketplacePaymentMethod":{"description":"String with field's key and value.","example":"credit card","title":"marketplacePaymentMethod","type":"string"}},"required":["marketplacePaymentMethod"],"title":"Fields","type":"object"},"GeoCoordinates":{"description":"Structure with the address geocoordinates. Optional for `delivery` orders, required for `pickup-in-point` orders.","properties":{"latitude":{"description":"Double value with the latitude coordinates of the address. Required only if the geoCoordinates field is defined. \n\nExample format: `-25.4158764`.","example":"-25.4158764","title":"latitude","type":"string"},"longitude":{"description":"Double value with the longitude coordinates of the address. Required only if the geoCoordinates field is defined. Example format: `-49.342759`.","example":"-49.342759","title":"longitude","type":"string"}},"required":["latitude","longitude"],"title":"GeoCoordinates","type":"object"},"InvoiceData":{"description":"Object with the order's billing data.","example":{"userPaymentInfo":{"paymentMethods":["creditCardPaymentGroup"]}},"properties":{"userPaymentInfo":{"$ref":"#/components/schemas/UserPaymentInfo"}},"required":["userPaymentInfo"],"title":"InvoiceData","type":"object"},"Item":{"example":{"id":"1","price":975,"quantity":1},"properties":{"id":{"description":"String with the SKU ID in VTEX’s catalog.","example":"1","title":"id","type":"string"},"price":{"description":"Integer with the SKU’s unit price. If the value is `USD110.50`, convert it to the format → `11050`.","example":11050,"title":"price","type":"integer"},"quantity":{"description":"Integer with the quantity of the SKU present in the order. The value should be greater than zero.","example":10,"title":"quantity","type":"integer"}},"required":["id","price","quantity"],"title":"Item","type":"object"},"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.","example":{"deliveryIds":{"warehouseId":"AR1"},"lockTTL":"1d","price":2050,"selectedDeliveryChannel":"delivery","selectedSla":"Express","shippingEstimate":"2d"},"properties":{"deliveryIds":{"$ref":"#/components/schemas/DeliveryIds"},"lockTTL":{"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","title":"lockTTL","type":"string"},"price":{"description":"Integer indicating the shipping price for this SKU. If the value is `USD20.50`, convert it to the format → `2050`.","example":2050,"title":"price","type":"integer"},"selectedDeliveryChannel":{"description":"String with the selected delivery channel. This field supports the following values:  \n\n- `delivery`,  \n\n- `pickup-in-point`.","example":"delivery","title":"selectedDeliveryChannel","type":"string"},"selectedSla":{"description":"String with the selected delivery SLA.","example":"T-G1-2-Express","title":"selectedSla","type":"string"},"shippingEstimate":{"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","title":"shippingEstimate","type":"string"}},"required":["price","selectedDeliveryChannel","selectedSla","lockTTL","shippingEstimate","deliveryIds"],"title":"LogisticsInfo","type":"object"},"Pickup-in-point":{"example":{"accountName":"grocery1","code":"SOI003","errors":null,"fields":null,"flow":"PlaceOrder","marketplaceOrderId":null,"message":"Order successfully enqueued","operationId":null,"success":true},"properties":{"accountName":{"description":"String that indicates which account made the request.","example":"accountName","type":"string"},"code":{"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","type":"string"},"errors":{"description":"List with errors related to the response, if there's any.","items":{"example":{"code":"FMT005","description":"Message describing the error.","source":"Fulfillment"},"properties":{"code":{"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","title":"code","type":"string"},"description":{"description":"String containing the error message/description returned by the source.","example":"Message describing the error.","title":"description","type":"string"},"source":{"description":"Includes the following fields pointing out the context of the error: \n\n`Fulfillment` \n\n`Checkout` \n\n`Order Integration`","example":"Fulfillment","title":"Checkout","type":"string"}},"required":["source","code","description"],"title":"errors","type":"object"},"nullable":true,"type":"array"},"fields":{"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.","example":{"franchiseOrderId":"38475934875"},"nullable":true,"properties":{"fields":{"example":{"franchiseOrderId":"432874921387409182347","mainOrderId":"MKP-123456789"},"properties":{"franchiseOrderId":{"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","title":"The franchiseOrderId Schema","type":"string"},"mainOrderId":{"description":"String with the order's ID inside the main seller account in VTEX.","example":"MKP-123456789","title":"mainOrderId","type":"string"}},"required":["mainOrderId"],"title":"fields","type":"object"}},"type":"object"},"flow":{"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","type":"string"},"marketplaceOrderId":{"description":"String that indicates the order's ID in the marketplace.","example":"7e62fcd3-827b-400d-be8a-f050a79c4976","nullable":true,"type":"string"},"message":{"description":"String with a message explaining the code returned in the response. ","example":"The order was integrated into VTEX successfully","type":"string"},"operationId":{"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","nullable":true,"type":"string"},"success":{"description":"Boolean that indicates if the response is successful or not.","example":true,"type":"boolean"}},"required":["marketplaceOrderId","accountName","code","flow","success","operationId","errors","fields","message"],"title":"Pickup-in-point","type":"object"},"Pickup-in-pointfranchise":{"example":{"accountName":"grocery1","code":"SOI003","errors":null,"fields":null,"flow":"PlaceOrder","marketplaceOrderId":null,"message":"Order successfully enqueued","operationId":null,"success":true},"properties":{"accountName":{"description":"String that indicates which account made the request.","example":"accountName","type":"string"},"code":{"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","type":"string"},"errors":{"description":"List with errors related to the response, if there's any.","items":{"example":{"code":"FMT005","description":"Message describing the error.","source":"Fulfillment"},"properties":{"code":{"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","title":"code","type":"string"},"description":{"description":"String containing the error message/description returned by the source.","example":"Message describing the error.","title":"description","type":"string"},"source":{"description":"Includes the following fields pointing out the context of the error: \n\n`Fulfillment` \n\n`Checkout` \n\n`Order Integration`","example":"Fulfillment","title":"Checkout","type":"string"}},"required":["source","code","description"],"title":"errors","type":"object"},"nullable":true,"type":"array"},"fields":{"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.","example":{"franchiseOrderId":"38475934875","mainOrderId":"MKP-123456789"},"nullable":true,"properties":{"fields":{"example":{"franchiseOrderId":"432874921387409182347","mainOrderId":"MKP-123456789"},"properties":{"franchiseOrderId":{"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","title":"The franchiseOrderId Schema","type":"string"},"mainOrderId":{"description":"String with the order’s ID inside the main seller account in VTEX.","example":"MKP-123456789","title":"The mainOrderId Schema","type":"string"}},"required":["mainOrderId"],"title":"fields","type":"object"}},"type":"object"},"flow":{"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","type":"string"},"marketplaceOrderId":{"description":"String that indicates the order's ID in the marketplace.","example":"7e62fcd3-827b-400d-be8a-f050a79c4976","nullable":true,"type":"string"},"message":{"description":"String with a message explaining the code returned in the response. ","example":"The order was integrated into VTEX successfully","type":"string"},"operationId":{"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","nullable":true,"type":"string"},"success":{"description":"Boolean that indicates if the response is successful or not.","example":true,"type":"boolean"}},"required":["marketplaceOrderId","accountName","code","flow","success","operationId","errors","fields","message"],"title":"Pickup-in-pointfranchise","type":"object"},"SelectedAddress":{"description":"List with the delivery addresses selected for the order. We currently only support a single delivery address.","properties":{"addressId":{"description":"String with the address identifier. Optional for `delivery` type orders, and required for `pickup-in-point` orders.","example":"1","title":"addressId","type":"string"},"addressType":{"description":"String with the address type. The field supports the values: `residential`, `commercial`, `pickup`.","example":"commercial","title":"addressType","type":"string"},"city":{"description":"String with the city’s name.","example":"City","title":"city","type":"string"},"complement":{"description":"String with the address' complement, like building name, or extra number.","example":"Complement to address","title":"complement","type":"string"},"country":{"description":"String with the state's name, filled in with three letter code.","example":"BRA","title":"country","type":"string"},"geoCoordinates":{"$ref":"#/components/schemas/GeoCoordinates"},"neighborhood":{"description":"String with the neighborhood's name.","example":"Neighborhood's name","title":"The neighborhood schema","type":"string"},"number":{"description":"String with the street's number.","example":"1986","title":"The number","type":"string"},"postalCode":{"description":"String with the address' postal code.","example":"81020-235","title":"postalCode","type":"string"},"receiverName":{"description":"String with the name of the person responsible for receiving the order.","example":"Yennefer of Vengerberg","title":"receiverName","type":"string"},"state":{"description":"String with the state's name, filled in with two letter code.","example":"RJ","title":"state","type":"string"},"street":{"description":"String with the street's name.","example":"The Witcher Avenue","title":"street","type":"string"}},"required":["addressType","addressId","receiverName","postalCode","country"],"title":"SelectedAddress","type":"object"},"ShippingData":{"properties":{"isFob":{"description":"Boolean that indicates whether the order's delivery is the marketplace responsibility. Optional, defaulting to false.","example":false,"title":"isFob","type":"boolean"},"isMarketplaceFulfillment":{"description":"Boolean that indicates whether the order's inventory in warehouse is the marketplace's responsibility. Optional, defaulting to false.","example":false,"title":"isMarketplaceFulfillment","type":"boolean"},"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.","items":{"$ref":"#/components/schemas/LogisticsInfo"},"type":"array"},"selectedAddresses":{"description":"","items":{"$ref":"#/components/schemas/SelectedAddress"},"type":"array"}},"required":["logisticsInfo","selectedAddresses","isFob","isMarketplaceFulfillment"],"title":"ShippingData","type":"object"},"UpdateOrderStatusRequest":{"example":{"connectorEndpoint":"https://connector-endpoint.com/api/vtex","connectorName":"Skyhub","marketplaceOrderId":"{{$guid}}","marketplaceOrderStatus":"APPROVED"},"properties":{"connectorEndpoint":{"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","title":"connectorEndpoint","type":"string"},"connectorName":{"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","title":"connectorName","type":"string"},"marketplaceOrderId":{"description":"String that indicates the order's ID in the marketplace.","example":"7e62fcd3-827b-400d-be8a-f050a79c4976","type":"string"},"marketplaceOrderStatus":{"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. This field accepts the following values:  \n\n- `new`  \n\n- `approved`.","example":"new","title":"marketplaceOrderStatus","type":"string"}},"required":["marketplaceOrderId","marketplaceOrderStatus","connectorName","connectorEndpoint"],"title":"UpdateOrderStatusRequest","type":"object"},"UserPaymentInfo":{"description":"Structure with the order’s payment data. Required only if `invoiceData` is defined.","example":{"paymentMethods":["creditCardPaymentGroup"]},"properties":{"paymentMethods":{"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"],"items":{"type":"string"},"type":"array"}},"required":["paymentMethods"],"title":"UserPaymentInfo","type":"object"},"VtexMapperRegistration":{"properties":{"CategoryTreeProcessingNotificationEndpoint":{"description":"The `CategoryTreeProcessingNotificationEndpoint` is optional, and should be an endpoint from the external marketplace, that will be notified after the marketplace's category tree is successfully processed or not.","example":"https://CategoryTreeProcessingNotificationEndpoint.com/api","type":"string"},"categoryTreeEndPoint":{"description":"Endpoint that returns categories and attributes according to VTEX  Mapper specifications.","example":"http://api.vtexinternal.com.br/api/{{marketplaceName}}/mapper/categories","type":"string"},"displayName":{"description":"Marketplace Name, that will be displayed in VTEX Mapper.","example":"Marketplace A","type":"string"},"mappingEndPoint":{"description":"Secure endpoint that will receive the category mapping sent by VTEX Mapper.","example":"http://api.vtexinternal.com.br/api/{{marketplaceName}}/mapper/mapping","type":"string"},"properties":{"description":"Refers to the `allowsRemap` property.","items":{"properties":{"allowsRemap":{"description":"Allows rempaping categories in case the marketplace or seller tree is altered. If marked as `true`, all trees will be remapped.","example":false,"type":"boolean"}},"type":"object"},"required":["allowsRemap"],"type":"object"}},"required":["displayName","categoryTreeEndPoint","mappingEndPoint","properties"],"type":"object"},"bundleItemsItem":{"properties":{"id":{"description":"Service identifier.","example":7436,"type":"integer"},"name":{"description":"Service name.","example":"name","type":"string"},"price":{"description":"Service price. The last two digits are the cents.","example":10,"type":"integer"},"type":{"description":"Service type.","example":"type","type":"string"}},"type":"object"},"fulfillmentItem":{"properties":{"id":{"description":"SKU ID.","example":"6","type":"string"},"quantity":{"description":"Quantity of items of the SKU in the cart.","example":1,"type":"integer"},"seller":{"description":"ID of the seller registered in VTEX.","example":"01","type":"string"}},"required":["id","quantity","seller"],"type":"object"},"itemAttachment":{"properties":{"content":{"description":"Content referring to the customization requested by the customer.","example":"content-example","type":"string"},"name":{"description":"Attachment name.","example":"name-example","type":"string"}},"type":"object"},"orderPlacement":{"properties":{"clientProfileData":{"description":"Customer's profile information.","properties":{"corporateDocument":{"description":"Corporate document, if the customer is a legal entity.","example":"12345678000100","nullable":true,"type":"string"},"corporateName":{"description":"Company name, if the customer is a legal entity.","example":"company-name","nullable":true,"type":"string"},"corporatePhone":{"description":"Corporate phone number, if the customer is a legal entity.","example":"+551100988887777","nullable":true,"type":"string"},"document":{"description":"Document number informed by the customer.","example":"123456789","type":"string"},"documentType":{"description":"Type of the document informed by the customer.","example":"cpf","type":"string"},"email":{"description":"Customer's email address.","example":"customer@examplemail.com","type":"string"},"firstName":{"description":"Customer's first name.","example":"first-name","type":"string"},"isCorporate":{"default":false,"description":"`true` if the customer is a legal entity.","nullable":true,"type":"boolean"},"lastName":{"description":"Customer's last name.","example":"last-name","type":"string"},"phone":{"description":"Customer's phone number.","example":"+55110988887777","type":"string"},"stateInscription":{"description":"State inscription, if the customer is a legal entity.","example":"12345678","nullable":true,"type":"string"},"tradeName":{"description":"Trade name, if the customer is a legal entity.","example":"trade-name","nullable":true,"type":"string"}},"required":["email","firstName","lastName","documentType","document","isCorporate"],"type":"object"},"items":{"description":"Array of objects containing data about each SKU in the cart.","items":{"properties":{"attachments":{"description":"Array containing information on attachments.","items":{},"type":"array"},"bundleItems":{"description":"Information on services sold along with the SKU. Example: a gift package.","items":{"$ref":"#/components/schemas/bundleItemsItem"},"type":"array"},"commission":{"description":"Comission.","example":0,"type":"integer"},"freightCommission":{"description":"Freight comission.","example":0,"type":"integer"},"id":{"description":"SKU ID.","example":"123456789abc","type":"string"},"isGift":{"description":"`true` if the item is a gift.","type":"boolean"},"itemsAttachment":{"description":"Attachments sold with the SKU.","items":{"$ref":"#/components/schemas/itemAttachment"},"type":"array"},"measurementUnit":{"description":"SKU measurement unit.","example":"g","type":"string"},"price":{"description":"SKU price. The last two digits are the cents. For example, $24.99 is represented 2499.","example":2499,"type":"integer"},"priceTags":{"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":{"properties":{"identifier":{"description":"Price tag identifier.","example":"1234abc-5678b-1234c","type":"string"},"isPercentual":{"description":"`true` if price tag value is applied through a percentage.","example":false,"type":"boolean"},"name":{"description":"Price tag name.","example":"discount@name-1234abc-5678b-1234c","type":"string"},"rawValue":{"description":"Price tag value.","example":-12,"type":"integer"},"value":{"description":"Price tag raw value.","example":-1200,"type":"integer"}},"type":"object"},"type":"array"},"quantity":{"description":"Quantity of the item.","example":1,"type":"integer"},"seller":{"description":"ID of the seller registered in VTEX.","example":"seller-example","type":"string"},"unitMultiplier":{"description":"SKU unit multiplier.","example":1,"type":"integer"}},"type":"object"},"type":"array"},"marketingData":{"description":"Marketing tracking data. If the order has no tracking data, the value will be `null`.","properties":{"utmCampaign":{"description":"UTM campaign","example":"Black friday","type":"string"},"utmMedium":{"description":"UTM medium.","example":"CPC","type":"string"},"utmSource":{"description":"UTM source.","example":"Facebook","type":"string"},"utmiCampaign":{"description":"utmi_campaign (internal utm)","example":"utmi_campaign-exmaple","type":"string"},"utmiPage":{"description":"utmi_page (internal utm)","example":"utmi_page-example","type":"string"},"utmiPart":{"description":"utmi_part (internal utm)","example":"utmi_part-exmaple","type":"string"}},"type":"object"},"marketplaceOrderId":{"description":"Identifies the order in the marketplace.","example":"1138342255777-01","type":"string"},"marketplacePaymentValue":{"description":"Amount that the marketplace agrees to pay to the seller. The last two digits are the cents. For example, $24.99 is represented 2499.","example":2499,"type":"integer"},"marketplaceServicesEndpoint":{"description":"Endpoint sent by VTEX to the seller, that will be used to send the invoice and tracking data to the marketplace. This endpoint will also be used in [change order in Multilevel Omnichannel Inventory](https://developers.vtex.com/docs/guides/change-orders-multilevel-omnichannel-inventory-external-marketplaces#implementators) operations in external marketplaces.","example":"https://marketplaceservicesendpoint.myvtex.com/","type":"string"},"openTextField":{"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","type":"string"},"paymentData":{"default":null,"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,"type":"object"},"shippingData":{"description":"Shipping information.","properties":{"address":{"description":"Shipping address.","properties":{"addressId":{"description":"Address ID.","example":"Home","type":"string"},"addressType":{"description":"Type of address. For example, `Residential` or `Pickup`, among others.","example":"residential","type":"string"},"city":{"description":"City of the shipping address.","example":"Rio de Janeiro","type":"string"},"complement":{"description":"Complement to the shipping address in case it applies.","example":"3rd floor","type":"string"},"country":{"description":"Three letter ISO code of the country of the shipping address.","example":"BRA","type":"string"},"geoCoordinates":{"description":"Array with two strings with geocoordinates, first latitude, then longitude.","items":{"example":"00.00000","type":"string"},"type":"array"},"neighborhood":{"description":"Neighborhood of the shipping address.","example":"Botafogo","type":"string"},"number":{"description":"Number of the building, house or apartment in the shipping address.","example":"300","type":"string"},"postalCode":{"description":"Postal Code.","example":"12345-000","type":"string"},"receiverName":{"description":"Name of the person who is going to receive the order.","example":"receiver-name","type":"string"},"reference":{"description":"Complement that might help locate the shipping address more precisely in case of delivery.","example":"Grey building","type":"string"},"state":{"description":"State of the shipping address.","example":"Rio de Janeiro","type":"string"},"street":{"description":"Street of the shipping address.","example":"Praia de Botafogo","type":"string"}},"required":["addressType","receiverName","postalCode","city","state","country","street","neighborhood","number"],"type":"object"},"logisticsInfo":{"description":"Array of objects containing logistics information of each item.","items":{"properties":{"deliveryWindow":{"description":"Scheduled delivery window information, in case it applies to the item.","properties":{"endDateUtc":{"description":"Scheduled delivery window end date in UTC.","example":"2025-08-15T13:51:41.077Z","type":"string"},"listPrice":{"description":"Scheduled delivery window list price.","example":10,"type":"number"},"startDateUtc":{"description":"Scheduled delivery window start date in UTC.","example":"2025-08-15T13:51:41.077Z","type":"string"}},"type":"object"},"itemIndex":{"description":"Index of the item in the `items` array, starting from 0.","example":0,"type":"integer"},"lockTTL":{"description":"Logistics reservation waiting time.","example":"8d","type":"string"},"price":{"description":"Shipping price for the item. Does not account for the whole order's shipping price.","example":1099,"type":"integer"},"selectedSla":{"description":"Selected shipping option","example":"Express","type":"string"},"shippingEstimate":{"description":"Estimated time until delivery for the item.","example":"7d","type":"string"}},"required":["itemIndex","selectedSla","price"],"type":"object"},"type":"array"},"updateStatus":{"description":"Indicate whether this object's information is up to date according to the order's items. An order can not be placed if `\"outdated\"`","example":"updated","type":"string"}},"type":"object"}},"type":"object"},"sendCategoryMappingToVtexMapper":{"properties":{"categories":{"default":[],"description":"Array with Marketplace parent categories and their information.","items":{"properties":{"children":{"default":[],"description":"Array with children categories in the marketplace, and their information.","items":{"properties":{"children":{"default":[],"description":"Grandchildren categories in the marketplace. Send as array of `ID`, `name` and `specifications`.","items":{},"nullable":true,"title":"children","type":"array"},"id":{"default":"1a","description":"ID of the child  category in the marketplace.","title":"id","type":"string"},"name":{"default":"Kitchen","description":"Name of the child  category in the marketplace.","title":"name","type":"string"},"specifications":{"default":[{"attributeName":"Color","attributeValues":[{"valueName":"Red"}],"required":true}],"description":"Specifications for the Product or SKU","items":{"description":"Specifications of children categories.","example":{"attributeName":"Color","attributeValues":[{"valueName":"Red"}],"required":true},"properties":{"attributeName":{"default":"Color","description":"Name of the attribute sent as a specification.","title":"attributeName","type":"string"},"attributeValues":{"default":[{"valueName":"Red"}],"description":"Values of the atttribute specified.","items":{"default":{"valueName":"Red"},"description":"Array of the multiple `valueNames` for the attribute specificied.","properties":{"valueName":{"default":"Red","description":"Name of the value","title":"valueName","type":"string"}},"required":["valueName"],"title":"valueName","type":"object"},"title":"attributeValues","type":"array"},"required":{"default":false,"description":"If the specification is required, mark this flag as `true`. If not, mark it as `false`.","title":"required","type":"boolean"}},"required":["attributeName","required","attributeValues"],"type":"object"},"title":"specifications","type":"array"}},"required":["id","name","children","specifications"],"type":"object"},"title":"chidren","type":"array"},"id":{"default":"1","description":"ID of the parent category in the marketplace.","title":"id","type":"string"},"name":{"default":"Appliances","description":"Name of the parent category in the marketplace.","title":"name","type":"string"}},"title":"","type":"object"},"required":["id","name","children"],"title":"","type":"array"}},"required":["categories","id","name"],"type":"object"}},"securitySchemes":{"appKey":{"in":"header","name":"X-VTEX-API-AppKey","type":"apiKey"},"appToken":{"in":"header","name":"X-VTEX-API-AppToken","type":"apiKey"}}}}