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