openapi: 3.0.0 info: title: VTex Marketplace Protocol 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/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orderForms/simulation) | Marketplace | Seller |\r\n| [Order placement](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders) | Marketplace | Seller |\r\n| [Authorize fulfillment](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-sellerOrderId-/fulfill) | Marketplace | Seller |\r\n| [Marketplace order cancellation](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-orderId-/cancel) | Marketplace | Seller |\r\n| [Send invoice](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice) | Seller | Marketplace |\r\n| [Send tracking information](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-) | Seller | Marketplace |\r\n| [Update tracking status](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-/tracking) | Seller | Marketplace |\r\n| [Cancel order in marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/cancel) | Seller | Marketplace |\r\n\r\nFor a detailed explanation of the steps required to develop a custom connector to sell products from an external seller in your storefront, check out our complete [External Seller Integration Guide](https://developers.vtex.com/docs/guides/external-seller-integration-guide).\r\n\r\n\r\n## External Marketplace\r\n\r\nIn this section, you will find the endpoints involved in the VTEX integration between an external marketplace and a VTEX seller.\r\n\r\n\r\n| **Request** | **From** | **To** |\r\n|-|-|-|\r\n| [VTEX Mapper Registration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/connector/register) | External marketplace | VTEX system |\r\n| [Send Category Mapping to VTEX Mapper](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/categories/marketplace/-id-) | External marketplace | VTEX system |\r\n| [New Order Integration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/order-integration/orders) | External marketplace | VTEX system |\r\n| [Update Order Status](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#put-/api/order-integration/orders/status) | External marketplace | VTEX system |\r\n| [Fulfillment simulation - External Marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/checkout/pub/orderForms/simulation) | External marketplace | VTEX system |\r\n| [Place fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders) | External marketplace | VTEX Seller |\r\n| [Authorize dispatch for fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders/-orderId-/fulfill) | External marketplace | VTEX Seller |\r\n\r\n\r\nFor a detailed explanation of the steps required to develop a custom connector to become an external marketplace for VTEX sellers, check out our complete [External Marketplace Integration Guide](https://developers.vtex.com/docs/guides/external-marketplace-integration-guide)." contact: {} version: '1.0' servers: - url: https://{accountName}.{environment}.com.br description: VTEX Server URL. variables: accountName: description: Name of the VTEX account. Used as part of the URL. default: apiexamples environment: description: Environment to use. Used as part of the URL. enum: - vtexcommercestable default: vtexcommercestable paths: /api/fulfillment/pvt/orders: post: tags: - External Marketplace summary: VTex Place fulfillment order description: "Creates fulfillment order, meaning that it is an order for the seller's side in a sale made through a marketplace. This order assumes the transaction itself has already happened on the marketplace's side and, therfore, cares only about the fulfillment side.\n\r\n\r> If you plan to integrate external orders with possible [Price divergence](https://help.vtex.com/en/tutorial/price-divergence-rule--6RlFLhD1rIRRshl83KnCjW#) be mindful of the `isCreatedAsync` request body field. \n\nFor a detailed explanation of the steps required to develop a custom connector to become an external marketplace for VTEX sellers, check out our complete [External Marketplace Integration Guide](https://developers.vtex.com/vtex-rest-api/docs/external-marketplace-integration-guide)." operationId: PlaceFulfillmentOrder parameters: - name: accountName in: path required: true description: Name of the VTEX account. Used as part of the URL. schema: type: string default: apiexamples - name: environment in: path required: true description: Environment to be used. It is passed as part of the URL. schema: type: string default: vtexcommercestable - name: Content-Type in: header description: Type of the content being sent. required: true style: simple schema: type: string default: application/json - name: Accept in: header description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand. required: true style: simple schema: type: string default: application/json - name: sc in: query description: Sales channel. required: false style: form schema: type: string example: '1' - name: affiliateId in: query description: ID identifying the marketplace where the order originates. This ID is configured in the seller's VTEX account, and should be informed to the marketplace. required: true style: form schema: type: string example: MKP requestBody: content: application/json: schema: type: object required: - marketplaceOrderId - marketplaceServicesEndpoint - marketplacePaymentValue - items - clientProfileData - shippingData properties: marketplaceOrderId: type: string description: ID of the order in the marketplace. example: '123456789' marketplaceServicesEndpoint: type: string description: Endpoint provided by the marketplace for post purchase communication. Should be an URL, containing protocol, host, path and query string (in case it applies). example: https://exampleseller.marketplaceservices.com marketplacePaymentValue: type: integer description: Value of the payment made to the marketplace. example: 100 isCreatedAsync: type: boolean description: Indicates whether an order is created. It must be `true` if an order is being placed with [Price divergence](https://help.vtex.com/en/tutorial/configuring-price-divergence-rule--awAKP0sS5J8jgLs2g7pPe), otherwise the request will not work. example: false items: type: array description: Array of objects containing information on each of the order's items. items: type: object required: - id - quantity - seller properties: id: type: string description: The SKU ID. example: '123' quantity: type: integer format: int32 description: The quantity of items of this specific SKU in the cart to be simulated. example: 1 seller: type: string description: The ID of the seller responsible for this SKU. This ID can be found in your VTEX Admin. example: '1' commission: type: integer description: Comission. example: 10 freightCommission: type: integer description: Freight comission example: 10 price: type: integer description: Item price within the context of the order without separating cents. For example, $24.99 is represented `2499`. example: 2499 bundleItems: type: array description: 'Information on services sold along with the SKU. Example: a gift package.' items: type: object properties: type: type: string description: Service type. example: type-example id: type: integer description: Service identifier. example: 1034 name: type: string description: Service name. example: name-example price: type: integer description: Service price. The last two digits are the cents. example: 199 itemAttachment: type: object description: Item attachment. properties: name: type: string description: Attachment name. example: name-example content: type: string description: Content referring to the customization requested by the customer. example: content-example attachments: type: array description: Array containing information on attachments. items: type: string priceTags: type: array description: Array of price tags, each of which, modifies the price in some way, like discounts or rates that apply to the item in the context of the order. items: type: object properties: identifier: type: string description: Price tag identifier. example: 1234abc-5678b-1234c isPercentual: type: boolean description: '`true` if price tag value is applied through a percentage.' default: false name: type: string description: Price tag name. example: discount@name-1234abc-5678b-1234c rawValue: type: integer description: Price tag value. example: -12 value: type: integer description: Price tag raw value. example: -1200 measurementUnit: type: string description: SKU measurement unit. example: g unitMultiplier: type: integer description: SKU unit multiplier. example: 1 isGift: type: boolean description: Indicates whether the order is a gift. default: false example: id: '123456789' quantity: 1 seller: '1' clientProfileData: type: object description: Customer's profile information. required: - email - firstName - lastName - documentType - document properties: email: type: string description: Customer's email address. example: customer@examplemail.com firstName: type: string description: Customer's first name. example: first-name lastName: type: string description: Customer's last name. example: last-name documentType: type: string description: Type of the document informed by the customer. example: cpf document: type: string description: Document informed by the customer. Validation depends on the country. example: '123456789' phone: type: string description: Customer's phone number. example: '+55110988887777' corporateName: type: string description: Company name, if the customer is a legal entity. example: company-name nullable: true tradeName: type: string description: Trade name, if the customer is a legal entity. example: trade-name nullable: true corporateDocument: type: string description: Corporate document, if the customer is a legal entity. example: '12345678000100' nullable: true stateInscription: type: string description: State inscription, if the customer is a legal entity. example: '12345678' nullable: true corporatePhone: type: string description: Corporate phone number, if the customer is a legal entity. example: '+551100988887777' nullable: true isCorporate: type: boolean description: '`true` if the customer is a legal entity.' example: false nullable: true shippingData: type: object description: Shipping information. properties: address: type: object description: Shipping address. required: - addressType - receiverName - postalCode - city - state - country - street - number properties: addressType: type: string description: Type of address. For example, `Residential` or `Pickup`, among others. example: residential receiverName: type: string description: Name of the person who is going to receive the order. example: receiver-name addressId: type: string description: Address ID. example: Home postalCode: type: string description: Postal Code. Validation depends on the country. example: '12345000' city: type: string description: City of the shipping address. example: Rio de Janeiro state: type: string description: State of the shipping address. example: Rio de Janeiro country: type: string description: Three letter ISO code of the country of the shipping address. example: BRA street: type: string description: Street of the shipping address. example: Praia de Botafogo number: type: string description: Number of the building, house or apartment in the shipping address. example: '300' neighborhood: type: string description: Neighborhood of the shipping address. example: Botafogo complement: type: string description: Complement to the shipping address in case it applies. example: 3rd floor reference: type: string description: Complement that might help locate the shipping address more precisely in case of delivery. example: Grey building geoCoordinates: type: array description: Array with two strings with geocoordinates, first latitude, then longitude. items: type: string example: '00.00000' logisticsInfo: type: array description: Array of objects containing logistics information of each item. items: 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: In case of scheduled delivery, this object will contain information on the delivery window selected by the shopper. properties: startDateUtc: type: string description: Delivery window starting day and time in UTC. example: '2021-07-13T00:00:00+00:00' endDateUtc: type: string description: Delivery window ending day and time in UTC. example: '2021-07-13T23:59:59+00:00' price: type: integer description: Delivery window price. default: 0 lisPrice: type: integer description: Delivery window list price. default: 0 tax: type: integer description: Delivery window tax. default: 0 updateStatus: type: string description: 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 paymentData: type: object description: In other contexts, this field tipically holds an object with payment information. However, since the payment is processed by the marketplace, it will be sent to the seller as `null` in this context. nullable: true default: marketingData: type: object 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 responses: '200': description: OK headers: {} content: application/json: examples: response: value: - marketplaceOrderId: '956' orderId: MBR-956 followUpEmail: 9762a2a9028a4b5d8eb9a8ff909d15ce@ct.vtex.com.br items: - id: '2' quantity: 1 seller: '1' priceTable: comission: 0 freightComission: 0 price: 13890 bundleItems: [] priceTags: [] measurementUnit: un unitMultiplier: 1 isGift: false clientProfileData: email: fba45537f5c84d4092cf064da742fe3d@ct.vtex.com.br firstName: Júlio lastName: Augusto de Oliveira documentType: cpf document: '11417984642' phone: '395555258' corporateName: tradeName: corporateDocument: stateInscription: corporatePhone: isCorporate: false userProfileId: shippingData: isFOB: false address: addressType: Residencial receiverName: Júlio Augusto de Oliveira addressId: Casa postalCode: '98776003' city: Americana state: SP country: BRA street: Rua da casa number: '31187' neighborhood: Grande circo complement: reference: Bairro do foca / Posto de Saúde 65 geoCoordinates: [] selectedaddresses: - addressType: Residencial receiverName: Júlio Augusto de Oliveira addressId: Casa postalCode: '98776003' city: Americana state: SP country: BRA street: Rua da casa number: '31187' neighborhood: Grande circo complement: reference: Bairro do foca / Posto de Saúde 65 geoCoordinates: [] logisticsInfo: - itemIndex: 0 selectedSla: Correios addressId: Casa selectedDeliveryChannel: delivery deliveryIds: - warehouseId: '1_1' dockId: '1' lockTTL: 8d shippingEstimate: 7d price: 1090 deliveryWindow: trackingHints: [] paymentData: customData: deprecated: false /api/fulfillment/pvt/orders/{orderId}/fulfill: post: tags: - External Marketplace summary: VTex Authorize dispatch for fulfillment order description: |- Creates fulfillment order, meaning that it is an order for the seller's side in a sale made through a marketplace. This order assumes the transaction itself has already happened on the marketplace's side and, therfore, cares only about the fulfillment side. For 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: - name: accountName in: path required: true description: Name of the VTEX account. Used as part of the URL. schema: type: string default: apiexamples - name: environment in: path required: true description: Environment to be used. It is passed as part of the URL. schema: type: string default: vtexcommercestable - name: orderId in: path required: true description: ID of the order that is to be authorized. It is composed of the `afilliateId` and the `marketplaceOrderId` joined with a `-`. For instance, an order with an ID `"123"` coming from the marketplace `"MKP"` has an `orderId` of `"MKP-123"`. schema: type: string default: MKP-123 - name: Content-Type in: header description: Type of the content being sent. required: true style: simple schema: type: string default: application/json - name: Accept in: header description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand. required: true style: simple schema: type: string default: application/json - name: sc in: query description: Sales channel. required: false style: form schema: type: string example: '1' - name: affiliateId in: query description: ID identifying the marketplace where the order originates. This ID is configured in the seller's VTEX account, and should be informed to the marketplace. required: true style: form schema: type: string example: MKP requestBody: content: application/json: schema: type: object properties: marketplaceOrderId: type: string description: ID of the order in the marketplace. It is the same as the `orderId` without the `afilliateId` at the beginning. For instance, if the `orderId` is `"MKP-123"`, the `marketplaceOrderId` is `"123"`. default: '123' responses: '200': description: OK headers: {} content: application/json: examples: response: value: marketplaceOrderId: '123' deprecated: false /api/order-integration/orders: post: tags: - External Marketplace summary: VTex New Order Integration description: |- API to integrate an external channel's order into the VTEX plataform. This 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}`. For 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: - name: Content-Type in: header description: Describes the type of the content being sent. required: true style: simple schema: type: string default: application/json - name: Accept in: header description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand. required: true style: simple schema: type: string default: application/json - name: an in: query description: Parameter should indicate the name of the VTEX account where the order is being integrated or updated, meaning the seller responsible for the order. required: false style: form explode: true schema: type: string example: apiexamples - name: accountName in: path required: true description: Parameter should indicate the name of the VTEX account where the order is being integrated or updated, meaning the seller responsible for the order. schema: type: string default: apiexamples - name: affiliateId in: query description: ID identifying the marketplace where the order originates. This ID is configured in the seller's VTEX account, and should be informed to the marketplace. required: true style: form explode: true schema: type: string example: MKP requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/EnqueueNewOrderRequest' example: marketplaceOrderId: '{{$guid}}' marketplaceOrderStatus: NEW marketplacePaymentValue: 3025 connectorName: SkyHub connectorEndpoint: https://connector-endpoint.com/api/vtex allowFranchises: false pickupAccountName: '' items: - id: '1' price: 975 quantity: 1 clientProfileData: email: email@email.com.br firstName: John lastName: Doe phone: '99999999999' document: '99999999999' corporateDocument: corporatePhone: corporateName: tradeName: stateInscription: shippingData: logisticsInfo: - price: 2050 selectedDeliveryChannel: delivery selectedSla: Express lockTTL: 1d shippingEstimate: 2d deliveryIds: warehouseId: AR1 selectedAddresses: - addressType: Residential addressId: '1' receiverName: John Doe postalCode: 81020-235 city: Curitiba state: PR country: BRA street: Rua Eduardo Carlos Pereira number: '4125' neighborhood: Portão complement: '101' geoCoordinates: latitude: '-29.5' longitude: '-45.8' isFob: true isMarketplaceFulfillment: true invoiceData: userPaymentInfo: paymentMethods: - creditCardPaymentGroup customData: customApps: - id: marketplace-integration major: 1 fields: marketplacePaymentMethod: credit card required: true responses: '200': description: OK headers: {} content: application/json: schema: $ref: '#/components/schemas/Deliverybyseller' example: marketplaceOrderId: accountName: grocery1 code: SOI003 flow: PlaceOrder success: true operationId: errors: fields: message: Order successfully enqueued default: description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/Deliverybyfranchiseseller' example: marketplaceOrderId: accountName: grocery1 code: SOI003 flow: PlaceOrder success: true operationId: errors: fields: message: Order successfully enqueued deprecated: false /api/order-integration/orders/status: put: tags: - External Marketplace summary: VTex Update Order Status description: |- API request used to update an order status in VTEX. This 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. For 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: - name: Content-Type in: header description: Describes the type of the content being sent. required: true style: simple schema: type: string default: application/json - name: Accept in: header description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand. required: true style: simple schema: type: string default: application/json - name: an in: query description: Parameter should indicate the name of the VTEX account where the order is being integrated or updated, meaning the seller responsible for the order. required: false style: form explode: true schema: type: string example: apiexamples - name: accountName in: path required: true description: Parameter should indicate the name of the VTEX account where the order is being integrated or updated, meaning the seller responsible for the order. schema: type: string default: apiexamples requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/UpdateOrderStatusRequest' example: marketplaceOrderId: '{{$guid}}' marketplaceOrderStatus: APPROVED connectorName: Skyhub connectorEndpoint: https://connector-endpoint.com/api/vtex required: true responses: '200': description: OK headers: {} content: application/json: schema: $ref: '#/components/schemas/Approveorder' example: marketplaceOrderId: 7e62fcd3-827b-400d-be8a-f050a79c4976 accountName: code: SOI003 flow: ApproveOrder success: true operationId: errors: fields: message: Order successfully enqueued deprecated: false /api/checkout/pub/orderForms/simulation: post: tags: - External Marketplace summary: VTex Fulfillment simulation - External Marketplace description: "This endpoint can be triggered by marketplaces to simulate the fulfillment of an item in the cart.\r\n\r\nThe fulfillment information is useful whenever you need to know the availability of fulfilling an order for a specific cart setting, since the API response will let you know the updated price, inventory and shipping data." operationId: fulfillment-simulation-external-marketplace parameters: - name: accountName in: path required: true description: Name of the VTEX account. Used as part of the URL. schema: type: string default: apiexamples - name: environment in: path required: true description: Environment to be used. It is passed as part of the URL. schema: type: string default: vtexcommercestable - name: Content-Type in: header description: Type of the content being sent. required: true style: simple schema: type: string default: application/json - name: Accept in: header description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand. required: true style: simple schema: type: string default: application/json - name: affiliateId in: query description: The affiliate ID code created by the seller. required: false style: form schema: type: string default: MNF - name: sc in: query description: Trade Policy (Sales Channel) identification. required: false style: form schema: type: integer example: 1 requestBody: content: application/json: schema: type: object required: - id - quantity - seller properties: items: type: array description: Array containing information about the SKUs inside the cart to be simulated. items: type: object properties: id: type: string description: The SKU ID. example: '1' quantity: type: integer format: int32 description: The quantity of items of this specific SKU in the cart to be simulated. example: 1 seller: type: string description: The ID of the seller responsible for this SKU. This ID can be found in your VTEX Admin. example: '1' marketingData: type: object description: Object containing promotion data such as coupon tracking information and internal or external UTMs. properties: coupon: type: string description: Sending an existing coupon code in this field will return the corresponding discount in the purchase. Use the [cart simulation](https://developers.vtex.com/vtex-rest-api/reference/orderform#orderformsimulation) request to check which coupons might apply before placing the order. default: free-shipping utmSource: type: string description: UTM source. default: Facebook utmMedium: type: string description: UTM medium. default: CPC utmCampaign: type: string description: UTM campaign default: Black friday utmiPage: type: string description: utmi_page (internal utm). default: utmi_page-example utmiPart: type: string description: utmi_part (internal utm). default: utmi_part-example utmiCampaign: type: string description: utmi_campaign (internal utm). default: utmi_campaign-example postalCode: type: string description: Postal code. example: 12345-000 country: type: string description: Three letter ISO code of the country of the shipping address. This value must be sent along with the `postalCode` or `geoCoordinates` values. example: BRA selectedSla: type: string description: SLA selected by the customer. example: Normal clientProfileData: type: object description: Customer's profile information. properties: email: type: string description: Email address. example: clark.kent@example.com firstName: type: string description: First name. example: Clark lastName: type: string description: Last name. example: Kent documentType: type: string description: Type of the document informed by the customer. example: cpf document: type: string description: Document informed by the customer. example: '12345678900' phone: type: string description: Phone number. example: '+552199999999' corporateName: type: string description: Company name, if the customer is a legal entity. nullable: true 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: Indicates whether the customer is a legal entity. profileCompleteOnLoading: type: boolean description: Indicates whether profile is complete on loading. profileErrorOnLoading: type: boolean description: Indicates whether profile presents error on loading. nullable: true customerClass: type: string description: Customer class. nullable: true geoCoordinates: type: array description: Array containing two floats with geocoordinates, first longitude, then latitude. default: - -47.924747467041016 - -15.832582473754883 items: type: number example: -47.924747467041016 isCheckedIn: type: boolean description: Indicates whether order is checked in. default: false storeId: type: string description: ID of the store. nullable: true responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: items: type: array description: Information on each item in the cart. items: type: object properties: id: type: string description: ID of the item. requestIndex: type: integer description: Request index information. quantity: type: integer description: The quantity of the item the cart. seller: type: string description: The seller responsible for the SKU. sellerChain: type: array description: Sellers involved in the chain. The list should contain only one seller, unless it is a [Multilevel Omnichannel Inventory](https://help.vtex.com/en/tutorial/multilevel-omnichannel-inventory--7M1xyCZWUyCB7PcjNtOyw4) order. items: type: string description: Seller. tax: type: integer description: Tax value in cents. priceValidUntil: type: string description: Price expiration date and time. price: type: integer description: Price in cents. listPrice: type: integer description: List price in cents. rewardValue: type: integer description: Reward value in cents. sellingPrice: type: integer description: Selling price in cents. Note that this field may be subject to rounding discrepancies. We recommend retrieving data from the `priceDefinition` data structure instead. offerings: type: array description: Array containing offering information. priceTags: type: array description: Array of price tags, each of which, modifies the price in some way, like discounts or rates that apply to the item in the context of the order. items: type: object properties: name: type: string description: Price tag name. value: type: integer description: Price tag value. rawValue: type: integer description: Price tag raw value. isPercentual: type: boolean description: Indicates whether price tag value is applied through a percentage. identifier: type: string description: Price tag identifier. owner: type: string description: Identification of the responsible for the price tag. measurementUnit: type: string description: Measurement unit. unitMultiplier: type: integer description: Unit multiplier. parentItemIndex: type: integer description: Parent item index. nullable: true parentAssemblyBinding: type: string description: Parent assembly binding. nullable: true availability: type: string description: Availability. priceDefinition: type: object description: Price information for all units of a specific item. properties: calculatedSellingPrice: type: integer description: Item's calculated unitary selling price in cents. total: type: integer description: Total value for all units of the item in cents. sellingPrices: type: array description: Array of objects, each containing value (in cents) and quantity for the different rounding instances that can be combined to form the correctly rounded total. items: type: object properties: value: type: integer description: Value in cents for that specific rounding. quantity: type: integer description: Rounding quantity, meaning how many items are rounded to this value. ratesAndBenefitsData: type: object description: Information on rates and benefits that apply to the order. properties: rateAndBenefitsIdentifiers: type: array description: List with rates and benefits identifiers. teaser: type: array description: List with rates and benefits teasers. paymentData: type: object description: Payment data information. properties: installmentOptions: type: array description: Installment options information. properties: paymentSystem: type: integer description: Payment system identification. bin: type: string description: Bin. nullable: true paymentName: type: string description: Payment name. paymentGroupName: type: string description: Payment group name. value: type: integer description: Total value assigned to this payment. installments: type: array description: Installments information. properties: count: type: integer description: Count information. hasInterestRate: type: boolean description: Indicates whether the payment has interest. interestRate: type: integer description: Interest rate value. value: type: integer description: Value of the order without the interest rate. The value is shown without separating cents. total: type: integer description: Total value of the order without separating cents. For example, $24.99 is represented `2499`. sellerMerchantInstallments: type: array description: Seller merchant installments information. paymentSystems: type: array description: Information on payment systems. items: type: object properties: id: type: integer description: Payment system ID. name: type: string description: Payment system name. groupName: type: string description: Payment group name. validator: type: object description: Payment system validator. nullable: true stringId: type: string description: String ID. template: type: string description: Template. requiresDocument: type: boolean description: Indicates whether a document is required. displayDocument: type: boolean description: Indicates whether a document is shown. isCustom: type: boolean description: Indicates whether it is custom. description: type: string description: Description. requiresAuthentication: type: boolean description: Indicates whether a authentication is required. dueDate: type: string description: Payment due date. availablePayments: type: string description: Availability of payment. nullable: true payments: type: array description: Information on each payment. giftCards: type: array description: Gift card information, if it applies to the order. giftCardMessages: type: array description: Array of gift card messages. availableAccounts: type: array description: Available accounts. availableTokens: type: array description: Available tokens. availableAssociations: type: object description: Available associations. selectableGifts: type: array description: Array containing the data of the item selected as a gift. marketingData: type: object description: Object containing promotion data such as coupon tracking information and internal or external UTMs. nullable: true postalCode: type: string description: Postal Code. nullable: true country: type: string description: Three letter ISO code of the country of the shipping address. logisticsInfo: type: array description: Array with logistics information on each item of the `items` array in the `orderForm`. items: type: object properties: itemIndex: type: integer description: Index of item in items array. addressId: type: string description: Address ID. nullable: true selectedSla: type: string description: Selected SLA. For example, `"normal"` or `"express"`. nullable: true selectedDeliveryChannel: type: string description: Delivery channel selected by the customer. For example, `"delivery"` or `"pickup-in-point"`. nullable: true quantity: type: integer description: Quantity. shipsTo: type: array description: List of countries that the item may be shipped to. slas: type: array description: Information on available SLAs. items: type: object properties: id: type: string description: SLA ID. deliveryChannel: type: string description: Delivery channel. name: type: string description: SLA name. deliveryIds: type: array description: Information on each delivery ID. items: type: object properties: courierId: type: string description: Courier ID. warehouseId: type: string description: Warehouse ID. dockId: type: string description: Warehouse ID. courierName: type: string description: Courier name. quantity: type: integer description: Quantity. shippingEstimate: type: string description: Shipping estimate. For instance, "three business days" will be represented as `3bd`. shippingEstimateDate: type: string description: Shipping estimate date. nullable: true lockTTL: type: string description: Estimate date of delivery. availableDeliveryWindows: type: object description: This object contains information about the delivery window available to the shopper. properties: startDateUtc: type: string description: Delivery window starting day and time in UTC. endDateUtc: type: string description: Delivery window ending day and time in UTC. price: type: integer description: Delivery window price. lisPrice: type: integer description: Delivery window list price. tax: type: integer description: Delivery window tax. deliveryWindow: type: object description: In case of scheduled delivery, this object will contain information on the delivery window selected by the shopper. properties: startDateUtc: type: string description: Delivery window starting day and time in UTC. endDateUtc: type: string description: Delivery window ending day and time in UTC. price: type: integer description: Delivery window price. lisPrice: type: integer description: Delivery window list price. tax: type: integer description: Delivery window tax. price: type: integer description: Price in cents. listPrice: type: integer description: List price in cents. tax: type: integer description: Tax in cents. pickupStoreInfo: type: object description: Information on the pickup store. properties: isPickupStore: type: boolean description: Indicates whether it is the pickup store. friendlyName: type: string description: Friendly name. nullable: true address: type: object description: Address information. nullable: true additionalInfo: type: string description: Additional information. nullable: true dockId: type: string description: Corresponding dock ID. nullable: true pickupPointId: type: string description: Pickup point ID. nullable: true pickupDistance: type: integer description: Pickup point distance. polygonName: type: string description: Polygon name. nullable: true transitTime: type: string description: Transit time. For instance, "three business days" is represented as `3bd`. deliveryChannels: type: array description: List of available delivery channels. items: type: object properties: id: type: string description: Delivery channel ID. messages: type: array description: Array containing an object for each message generated by our servers while processing the request. purchaseConditions: type: object description: Purchase conditions information. properties: itemPurchaseConditions: type: array description: List of objects containing purchase condition information on each item in the order. items: type: object properties: id: type: string description: Item ID. seller: type: string description: Seller. sellerChain: type: array description: Sellers involved in the chain. The list should contain only one seller, unless it is a [Multilevel Omnichannel Inventory](https://help.vtex.com/en/tutorial/multilevel-omnichannel-inventory--7M1xyCZWUyCB7PcjNtOyw4) order. slas: type: array description: Information on available SLAs. items: type: object properties: id: type: string description: SLA ID. deliveryChannel: type: string description: Delivery channel. name: type: string description: SLA name. deliveryIds: type: array description: Information on each delivery ID. items: type: object properties: courierId: type: string description: Courier ID. warehouseId: type: string description: Warehouse ID. dockId: type: string description: Warehouse ID. courierName: type: string description: Courier name. quantity: type: integer description: Quantity. shippingEstimate: type: string description: Shipping estimate. For instance, "three business days" will be represented as `3bd`. shippingEstimateDate: type: string description: Shipping estimate date. nullable: true lockTTL: type: string description: Estimate date of delivery. availableDeliveryWindows: type: object description: This object contains information about the delivery window available to the shopper. properties: startDateUtc: type: string description: Delivery window starting day and time in UTC. endDateUtc: type: string description: Delivery window ending day and time in UTC. price: type: integer description: Delivery window price. lisPrice: type: integer description: Delivery window list price. tax: type: integer description: Delivery window tax. deliveryWindow: type: object description: In case of scheduled delivery, this object will contain information on the delivery window selected by the shopper. properties: startDateUtc: type: string description: Delivery window starting day and time in UTC. endDateUtc: type: string description: Delivery window ending day and time in UTC. price: type: integer description: Delivery window price. lisPrice: type: integer description: Delivery window list price. tax: type: integer description: Delivery window tax. price: type: integer description: Price in cents. listPrice: type: integer description: List price in cents. tax: type: integer description: Tax in cents. pickupStoreInfo: type: object description: Information on the pickup store. properties: isPickupStore: type: boolean description: Indicates whether it is the pickup store. friendlyName: type: string description: Friendly name. nullable: true address: type: object description: Address information. nullable: true additionalInfo: type: string description: Additional information. nullable: true dockId: type: string description: Corresponding dock ID. nullable: true pickupPointId: type: string description: Pickup point ID. nullable: true pickupDistance: type: integer description: Pickup point distance. polygonName: type: string description: Polygon name. nullable: true transitTime: type: string description: Transit time. For instance, "three business days" is represented as `3bd`. price: type: integer description: Price in cents. listPrice: type: integer description: List price in cents. pickupPoints: type: array description: Array containing pickup points information. subscriptionData: type: object description: Subscription information. nullable: true totals: type: array description: Information on order totals. items: type: object properties: id: type: string description: Total ID. name: type: string description: Total name. value: type: integer description: Total value. itemMetadata: type: object description: Item metadata. properties: items: type: array description: List of objects containing metadata on each item in the order. items: type: object properties: id: type: string description: Item ID. seller: type: string description: Seller. assemblyOptions: type: array description: Assembly options information. properties: id: type: string description: Item ID. name: type: string description: Item name. required: type: boolean description: Indicates whether the item is required. inputValues: type: object description: Input values information. composition: type: string description: Composition information. nullable: true example: items: - id: '1' requestIndex: 0 quantity: 1 seller: '1' sellerChain: - '1' tax: 0 priceValidUntil: '2023-07-12T11:49:01Z' price: 9999 listPrice: 9999 rewardValue: 0 sellingPrice: 2999700 offerings: [] priceTags: - name: DISCOUNT@MANUALPRICE value: -5000 rawValue: -50 isPercentual: false identifier: 1234abc-5678b-1234c measurementUnit: un unitMultiplier: 300 parentItemIndex: parentAssemblyBinding: availability: available priceDefinition: calculatedSellingPrice: 2999700 total: 2999700 sellingPrices: - value: 2999700 quantity: 1 ratesAndBenefitsData: rateAndBenefitsIdentifiers: [] teaser: [] paymentData: installmentOptions: - paymentSystem: '2' bin: paymentName: Visa paymentGroupName: creditCardPaymentGroup value: 2999700 installments: - count: 1 hasInterestRate: false interestRate: 0 value: 2999700 total: 2999700 sellerMerchantInstallments: - id: LOJADOBRENO count: 1 hasInterestRate: false interestRate: 0 value: 2999700 total: 2999700 - paymentSystem: '6' bin: paymentName: Boleto Bancário paymentGroupName: bankInvoicePaymentGroup value: 2999700 installments: - count: 1 hasInterestRate: false interestRate: 0 value: 2999700 total: 2999700 sellerMerchantInstallments: - id: LOJADOBRENO count: 1 hasInterestRate: false interestRate: 0 value: 2999700 total: 2999700 - paymentSystem: '127' bin: paymentName: MercadoPagoPro paymentGroupName: MercadoPagoProPaymentGroup value: 2999700 installments: - count: 1 hasInterestRate: false interestRate: 0 value: 2999700 total: 2999700 sellerMerchantInstallments: - id: LOJADOBRENO count: 1 hasInterestRate: false interestRate: 0 value: 2999700 total: 2999700 - paymentSystem: '202' bin: paymentName: Dinheiro paymentGroupName: custom202PaymentGroupPaymentGroup value: 2999700 installments: - count: 1 hasInterestRate: false interestRate: 0 value: 2999700 total: 2999700 sellerMerchantInstallments: - id: LOJADOBRENO count: 1 hasInterestRate: false interestRate: 0 value: 2999700 total: 2999700 paymentSystems: - id: 202 name: Dinheiro groupName: custom202PaymentGroupPaymentGroup validator: stringId: '202' template: custom202PaymentGroupPaymentGroup-template requiresDocument: false displayDocument: false isCustom: true description: '' requiresAuthentication: false dueDate: '2022-07-22T11:39:36.37197Z' availablePayments: - id: 6 name: Boleto Bancário groupName: bankInvoicePaymentGroup validator: stringId: '6' template: bankInvoicePaymentGroup-template requiresDocument: false displayDocument: false isCustom: false description: '' requiresAuthentication: false dueDate: '2022-07-19T11:39:36.37197Z' availablePayments: - id: 2 name: Visa groupName: creditCardPaymentGroup validator: stringId: '2' template: creditCardPaymentGroup-template requiresDocument: false displayDocument: false isCustom: false description: '' requiresAuthentication: false dueDate: '2022-07-19T11:39:36.37197Z' availablePayments: - id: 127 name: MercadoPagoPro groupName: MercadoPagoProPaymentGroup validator: stringId: '127' template: MercadoPagoProPaymentGroup-template requiresDocument: false displayDocument: false isCustom: false description: '' requiresAuthentication: false dueDate: '2022-07-19T11:39:36.37197Z' availablePayments: payments: [] giftCards: [] giftCardMessages: [] availableAccounts: [] availableTokens: [] availableAssociations: {} selectableGifts: [] marketingData: utmSource: app utmMedium: CPC utmCampaign: Black friday utmipage: 'true' utmiPart: 'true' utmiCampaign: 'true' coupon: marketingTags: - tag1 - tag2 country: BRA postalCode: 12345-000 geoCoordinates: - -47.924747467041016 - -15.832582473754883 logisticsInfo: - itemIndex: 0 addressId: selectedSla: selectedDeliveryChannel: quantity: 1 shipsTo: - BRA slas: - id: Normal deliveryChannel: delivery name: Normal deliveryIds: - courierId: '1' warehouseId: '1_1' dockId: '1' courierName: Transportadora quantity: 1 kitItemDetails: [] shippingEstimate: 3bd shippingEstimateDate: lockTTL: 10d availableDeliveryWindows: startDateUtc: '2017-03-27T00:00:00+00:00' endDateUtc: '2017-03-27T00:00:00+00:00' price: 0 lisPrice: 0 tax: 0 deliveryWindow: startDateUtc: '2014-04-21T09:00:00+00:00' endDateUtc: '2014-04-21T12:00:00+00:00' price: 0 listprice: 1000 tax: 0 price: 1500 listPrice: 1500 tax: 0 pickupStoreInfo: isPickupStore: false friendlyName: address: additionalInfo: dockId: pickupPointId: pickupDistance: 0 polygonName: transitTime: 3bd deliveryChannels: - id: pickup-in-point - id: delivery messages: [] purchaseConditions: itemPurchaseConditions: - id: '1' seller: '1' sellerChain: - '1' slas: - id: Normal deliveryChannel: delivery name: Normal deliveryIds: - courierId: '1' warehouseId: '1_1' dockId: '1' courierName: Transportadora quantity: 1 kitItemDetails: [] shippingEstimate: 3bd shippingEstimateDate: lockTTL: 10d availableDeliveryWindows: startDateUtc: '2017-03-27T00:00:00+00:00' endDateUtc: '2017-03-27T00:00:00+00:00' price: 0 lisPrice: 0 tax: 0 deliveryWindow: startDateUtc: '2014-04-21T09:00:00+00:00' endDateUtc: '2014-04-21T12:00:00+00:00' price: 0 listprice: 1000 tax: 0 price: 1500 listPrice: 1500 tax: 0 pickupStoreInfo: isPickupStore: false friendlyName: address: additionalInfo: dockId: pickupPointId: pickupDistance: 0 polygonName: transitTime: 3bd price: 9999 listPrice: 9999 pickupPoints: [] subscriptionData: totals: - id: Items name: Total dos Itens value: 2999700 itemMetadata: items: - id: '1' seller: '1' assemblyOptions: - id: T-Shirt Customization name: T-Shirt Customization required: false inputValues: T-Shirt Name: maximumNumberOfCharacters: 2 domain: - '[]' composition: deprecated: false security: - appKey: [] appToken: [] components: schemas: EnqueueNewOrderRequest: title: EnqueueNewOrderRequest required: - marketplaceOrderId - marketplaceOrderStatus - marketplacePaymentValue - allowFranchises - items - clientProfileData - shippingData - invoiceData type: object properties: marketplaceOrderId: type: string title: marketplaceOrderId description: String that indicates the order's ID in the marketplace. example: 7e62fcd3-827b-400d-be8a-f050a79c4976 marketplaceOrderStatus: type: string title: 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: - `new` - `approved` example: new marketplacePaymentValue: type: integer title: 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 connectorName: type: string title: connectorName description: |- String with the identifier code of the connector responsible for the order. This 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`. It is required if the connector is native or does not use the App Template. example: connectorName connectorEndpoint: type: string title: 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: - `https://{{externalconnector}}.com` - `https://{{externalconnector.com}}/api/vtex` if you additionaly want to send a relative URL with the endpoint. This 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`. It is required if the connector is native or does not use the App Template. example: https://{{externalconnector.com}}/api/vtex allowFranchises: type: boolean title: 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 pickupAccountName: type: string title: 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 items: type: array items: $ref: '#/components/schemas/Item' clientProfileData: $ref: '#/components/schemas/ClientProfileData' shippingData: $ref: '#/components/schemas/ShippingData' invoiceData: $ref: '#/components/schemas/InvoiceData' customData: $ref: '#/components/schemas/CustomData' example: marketplaceOrderId: '{{$guid}}' marketplaceOrderStatus: NEW marketplacePaymentValue: 3025 connectorName: SkyHub connectorEndpoint: https://connector-endpoint.com/api/vtex allowFranchises: false pickupAccountName: '' items: - id: '1' price: 975 quantity: 1 clientProfileData: email: email@email.com.br firstName: John lastName: Doe phone: '99999999999' document: '99999999999' corporateDocument: corporatePhone: corporateName: tradeName: stateInscription: shippingData: logisticsInfo: - price: 2050 selectedDeliveryChannel: delivery selectedSla: Express lockTTL: 1d shippingEstimate: 2d deliveryIds: warehouseId: AR1 selectedAddresses: - addressType: Residential addressId: '1' receiverName: John Doe postalCode: 81020-235 city: Curitiba state: PR country: BRA street: Rua Eduardo Carlos Pereira number: '4125' neighborhood: Portão complement: '101' geoCoordinates: latitude: '-29.5' longitude: '-45.8' isFob: true isMarketplaceFulfillment: true invoiceData: userPaymentInfo: paymentMethods: - creditCardPaymentGroup customData: customApps: - id: marketplace-integration major: 1 fields: marketplacePaymentMethod: credit card Item: title: Item required: - id - price - quantity type: object properties: id: type: string title: id description: String with the SKU ID in VTEX’s catalog. example: '1' price: type: integer title: price description: Integer with the SKU’s unit price. If the value is `USD110.50`, convert it to the format → `11050`. example: 11050 quantity: type: integer title: quantity description: Integer with the quantity of the SKU present in the order. The value should be greater than zero. example: 10 example: id: '1' price: 975 quantity: 1 ClientProfileData: title: ClientProfileData description: Structure with the customer's information. An order will be identified as corporate if any of the corporate fields are filled out (`corporateDocument`, `corporatePhone`, `corporateName` or `tradeName`). required: - email - firstName - lastName - phone - document - corporateDocument - corporatePhone - corporateName - tradeName - stateInscription type: object properties: email: type: string title: email description: String with the customer's email. example: cirilla@cintra.com firstName: type: string title: firstName description: String with the customer's first name. example: Cirilla lastName: type: string title: lastName description: String with the customer’s surname. example: Cintra phone: type: string title: phone description: String with the customer’s phone number. example: '99999999999' document: type: string title: The document schema description: String with the customer’s document number. example: '99999999999' corporateDocument: type: string title: corporateDocument description: String with the company’s document number, in case of corporate orders. nullable: true example: '99999999999' corporatePhone: type: string title: corporatePhone description: String with the company’s phone number, in case of corporate orders. nullable: true example: '99999999999' corporateName: type: string title: corporateName description: String with the company’s name, in case of corporate orders. nullable: true example: The Witcher Inc. tradeName: type: string title: tradeName description: String with the company’s fantasy name, in case of corporate orders. nullable: true example: The Witcher stateInscription: type: string title: stateInscription description: String with the company’s state registration, in case of corporate orders. nullable: true example: '99999999999' ShippingData: title: ShippingData required: - logisticsInfo - selectedAddresses - isFob - isMarketplaceFulfillment type: object properties: logisticsInfo: type: array items: $ref: '#/components/schemas/LogisticsInfo' description: |- List that references the SLAs responsible for delivering each item in the order. This 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). The 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. selectedAddresses: type: array items: $ref: '#/components/schemas/SelectedAddress' description: '' isFob: type: boolean title: isFob description: Boolean that indicates whether the order's delivery is the marketplace responsibility. Optional, defaulting to false. example: false isMarketplaceFulfillment: type: boolean title: isMarketplaceFulfillment description: Boolean that indicates whether the order's inventory in warehouse is the marketplace's responsibility. Optional, defaulting to false. example: false LogisticsInfo: title: LogisticsInfo description: |- List that references the SLAs responsible for delivering each item in the order. This 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). The order of the SLAs in this list must also follow the same order as in the `items` list. For example: if the SLA named **Correios Express** will be responsible for delivering the SKU with ID equal to **1015**, which is found at index 0 of the `items` list, it must be in index 0 of the `logisticsInfo` list as well. required: - price - selectedDeliveryChannel - selectedSla - lockTTL - shippingEstimate - deliveryIds type: object properties: price: type: integer title: price description: Integer indicating the shipping price for this SKU. If the value is `USD20.50`, convert it to the format → `2050`. example: 2050 selectedDeliveryChannel: type: string title: selectedDeliveryChannel description: |- String with the selected delivery channel. This field supports the following values: - `delivery`, - `pickup-in-point`. example: delivery selectedSla: type: string title: selectedSla description: String with the selected delivery SLA. example: T-G1-2-Express lockTTL: type: string title: 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. - Days: `d` - Business days: `bd`. Example formats: `12d`, `5d`. example: 5d shippingEstimate: type: string title: 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. - Days: `d` - Business days: `bd`. - Hours: `h` - Minutes: `m`. Example formats: `12d`, `5bd`, `3h`, `50m`. example: 7d deliveryIds: $ref: '#/components/schemas/DeliveryIds' example: price: 2050 selectedDeliveryChannel: delivery selectedSla: Express lockTTL: 1d shippingEstimate: 2d deliveryIds: warehouseId: AR1 DeliveryIds: title: 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. required: - warehouseId type: object properties: warehouseId: type: string description: String with the ID of the warehouse used for marketplace fulfillment. Required when `isFob` = `true` and `isMarketplaceFulfillment` = `true`. example: AR1 example: warehouseId: AR1 SelectedAddress: title: SelectedAddress description: List with the delivery addresses selected for the order. We currently only support a single delivery address. required: - addressType - addressId - receiverName - postalCode - country type: object properties: addressType: type: string title: addressType description: 'String with the address type. The field supports the values: `residential`, `commercial`, `pickup`.' example: commercial addressId: type: string title: addressId description: String with the address identifier. Optional for `delivery` type orders, and required for `pickup-in-point` orders. example: '1' receiverName: type: string title: receiverName description: String with the name of the person responsible for receiving the order. example: Yennefer of Vengerberg postalCode: type: string title: postalCode description: String with the address' postal code. example: 81020-235 city: type: string title: city description: String with the city’s name. example: City state: type: string title: state description: String with the state's name, filled in with two letter code. example: RJ country: type: string title: country description: String with the state's name, filled in with three letter code. example: BRA street: type: string title: street description: String with the street's name. example: The Witcher Avenue number: type: string title: The number description: String with the street's number. example: '1986' neighborhood: type: string title: The neighborhood schema description: String with the neighborhood's name. example: Neighborhood's name complement: type: string title: complement description: String with the address' complement, like building name, or extra number. example: Complement to address geoCoordinates: $ref: '#/components/schemas/GeoCoordinates' GeoCoordinates: title: GeoCoordinates description: Structure with the address geocoordinates. Optional for `delivery` orders, required for `pickup-in-point` orders. required: - latitude - longitude type: object properties: latitude: type: string title: latitude description: |- Double value with the latitude coordinates of the address. Required only if the geoCoordinates field is defined. Example format: `-25.4158764`. example: '-25.4158764' longitude: type: string title: 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' InvoiceData: title: InvoiceData description: Object with the order's billing data. required: - userPaymentInfo type: object properties: userPaymentInfo: $ref: '#/components/schemas/UserPaymentInfo' example: userPaymentInfo: paymentMethods: - creditCardPaymentGroup UserPaymentInfo: title: UserPaymentInfo description: Structure with the order’s payment data. Required only if `invoiceData` is defined. required: - paymentMethods type: object properties: paymentMethods: type: array items: type: string description: List of strings with the payment methods used in the order. Required only if `invoiceData` is defined. The format and some possible values of payment methods accepted in this list can be found in the call [Fetching marketplace information with the Orders API](https://developers.vtex.com/vtex-rest-api/docs/get-marketplace-data-orders-api). example: - creditCardPaymentGroup example: paymentMethods: - creditCardPaymentGroup CustomData: title: CustomData description: Structure with the order's customizable fields. To insert custom fields in the order, you must first go through the process of [Creating an app](https://developers.vtex.com/vtex-rest-api/docs/external-marketplace-integration-app-template), and then adding the app, as well as the desired fields, within the seller's `orderForm`. More information on [Creating customizable fields in the cart with Checkout API](https://developers.vtex.com/vtex-rest-api/docs/customizable-fields-with-checkout-api). required: - customApps type: object properties: customApps: type: array items: $ref: '#/components/schemas/CustomApp' description: Array of objects with information about custom apps. example: customApps: - id: marketplace-integration major: 1 fields: marketplacePaymentMethod: credit card CustomApp: title: CustomApp required: - id - major - fields type: object properties: id: type: string title: id description: App's ID. example: ID major: type: integer title: major description: Integer with the major version of the app. Optional, defaulting to one. example: 1 fields: $ref: '#/components/schemas/Fields' example: id: marketplace-integration major: 1 fields: marketplacePaymentMethod: credit card Fields: title: Fields description: String dictionary with the names of the fields and their respective values that must be inserted into the order. required: - marketplacePaymentMethod type: object properties: marketplacePaymentMethod: type: string title: marketplacePaymentMethod description: String with field's key and value. example: credit card example: marketplacePaymentMethod: credit card Deliverybyseller: title: Deliverybyseller required: - marketplaceOrderId - accountName - code - flow - success - operationId - errors - fields - message type: object properties: marketplaceOrderId: type: string nullable: true description: String that indicates the order's ID in the marketplace. example: 7e62fcd3-827b-400d-be8a-f050a79c4976 accountName: type: string description: String that indicates which account made the request. example: accountName code: type: string description: String with a internal Channel Order API code that classifies the response. The possible values returned in this field are described in the [Response Codes]() section. example: SOI001 flow: type: string description: |- String containing the name of the flow responsible for the response. This field can contain the following values: `PlaceOrder`: when integrating new orders `ApproveOrder`: when approving existing orders `Unknown`: when we’re not able to identify the flow example: ApproveOrder success: type: boolean description: Boolean that indicates if the response is successful or not. example: true operationId: type: string nullable: true description: String GUID that identifies the operation in our service. This field can be used to help us analyze unexpected errors or behaviors. example: '1234567' errors: type: array nullable: true description: List with errors related to the response, if there's any. items: type: object title: errors required: - source - code - description properties: source: type: string title: Checkout description: |- Includes the following fields pointing out the context of the error: `Fulfillment` `Checkout` `Order Integration` example: Fulfillment code: type: string title: 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 description: type: string title: description description: String containing the error message/description returned by the source. example: Message describing the error. example: source: Fulfillment code: FMT005 description: Message describing the error. fields: type: object nullable: true description: |- Structure with important fields for the connector. This structure is only returned if the response is successful. Includes the following fields: `mainOrderId`: String with the order's ID inside the main seller account in VTEX. `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: - `allowFranchises` field set to `true` when integrating the order - `SLA` chosen for the order is from a franchise account. properties: fields: type: object title: fields required: - mainOrderId properties: mainOrderId: type: string title: mainOrderId description: String with the order’s ID inside the main seller account in VTEX. example: MKP-123456789 franchiseOrderId: type: string title: 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' example: mainOrderId: MKP-123456789 franchiseOrderId: '432874921387409182347' example: franchiseOrderId: '38475934875' message: type: string description: 'String with a message explaining the code returned in the response. ' example: The order was integrated into VTEX successfully example: marketplaceOrderId: accountName: grocery1 code: SOI003 flow: PlaceOrder success: true operationId: errors: fields: message: Order successfully enqueued Deliverybyfranchiseseller: title: Deliverybyfranchiseseller required: - marketplaceOrderId - accountName - code - flow - success - operationId - errors - fields - message type: object properties: marketplaceOrderId: type: string nullable: true description: String that indicates the order's ID in the marketplace. example: 7e62fcd3-827b-400d-be8a-f050a79c4976 accountName: type: string description: String that indicates which account made the request. example: accountName code: type: string description: String with a internal Channel Order API code that classifies the response. The possible values returned in this field are described in the [Response Codes]() section. example: SOI001 flow: type: string description: |- String containing the name of the flow responsible for the response. This field can contain the following values: `PlaceOrder`: when integrating new orders `ApproveOrder`: when approving existing orders `Unknown`: when we’re not able to identify the flow example: ApproveOrder success: type: boolean description: Boolean that indicates if the response is successful or not. example: true operationId: type: string nullable: true description: String GUID that identifies the operation in our service. This field can be used to help us analyze unexpected errors or behaviors. example: '1234567' errors: type: array nullable: true description: List with errors related to the response, if there's any. items: type: object title: errors required: - source - code - description properties: source: type: string title: Checkout description: |- Includes the following fields pointing out the context of the error: `Fulfillment` `Checkout` `Order Integration` example: Fulfillment code: type: string title: 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 description: type: string title: description description: String containing the error message/description returned by the source. example: Message describing the error. example: source: Fulfillment code: FMT005 description: Message describing the error. fields: type: object nullable: true description: |- Structure with important fields for the connector. This structure is only returned if the response is successful. Includes the following fields: `mainOrderId`: String with the order's ID inside the main seller account in VTEX. `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: - `allowFranchises` field set to `true` when integrating the order - `SLA` chosen for the order is from a franchise account. properties: fields: type: object title: fields required: - mainOrderId properties: mainOrderId: type: string title: mainOrderId description: String with the order’s ID inside the main seller account in VTEX. example: MKP-123456789 franchiseOrderId: type: string title: 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' example: mainOrderId: MKP-123456789 franchiseOrderId: '432874921387409182347' example: franchiseOrderId: '38475934875' message: type: string description: 'String with a message explaining the code returned in the response. ' nullable: true example: The order was integrated into VTEX successfully example: marketplaceOrderId: accountName: grocery1 code: SOI003 flow: PlaceOrder success: true operationId: errors: fields: message: Order successfully enqueued UpdateOrderStatusRequest: title: UpdateOrderStatusRequest required: - marketplaceOrderId - marketplaceOrderStatus - connectorName - connectorEndpoint type: object properties: marketplaceOrderId: type: string description: String that indicates the order's ID in the marketplace. example: 7e62fcd3-827b-400d-be8a-f050a79c4976 marketplaceOrderStatus: type: string title: 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: - `new` - `approved`. example: new connectorName: type: string title: connectorName description: |- String with the identifier code of the connector responsible for the order. This 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`. It is required if the connector is native or does not use the App Template. example: connectorName connectorEndpoint: type: string title: 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: - `https://{{externalconnector}}.com` - `https://{{externalconnector.com}}/api/vtex` if you additionaly want to send a relative URL with the endpoint. This 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`. It is required if the connector is native or does not use the App Template. example: https://{{externalconnector.com}}/api/vtex example: marketplaceOrderId: '{{$guid}}' marketplaceOrderStatus: APPROVED connectorName: Skyhub connectorEndpoint: https://connector-endpoint.com/api/vtex Approveorder: title: Approveorder required: - marketplaceOrderId - accountName - code - flow - success - operationId - errors - fields - message type: object properties: marketplaceOrderId: type: string nullable: true description: String that indicates the order's ID in the marketplace. example: 7e62fcd3-827b-400d-be8a-f050a79c4976 accountName: type: string description: String that indicates which account made the request. example: accountName nullable: true code: type: string description: String with a internal Channel Order API code that classifies the response. The possible values returned in this field are described in the Response Codes section of this API Reference. example: SOI001 flow: type: string description: |- String containing the name of the flow responsible for the response. This field can contain the following values: `PlaceOrder`: when integrating new orders. `ApproveOrder`: when approving existing orders. `Unknown`: when we’re not able to identify the flow. example: ApproveOrder success: type: boolean description: Boolean that indicates if the response is successful or not. example: true operationId: type: string nullable: true description: String GUID that identifies the operation in our service. This field can be used to help us analyze unexpected errors or behaviors. example: '1234567' errors: type: array nullable: true description: List with errors related to the response, if there is any. items: type: object title: errors required: - source - code - description properties: source: type: string title: Checkout description: |- Includes the following fields pointing out the context of the error: `Fulfillment` `Checkout` `Order Integration` example: Fulfillment code: type: string title: 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 description: type: string title: description description: String containing the error message/description returned by the source. example: Message describing the error. example: source: Fulfillment code: FMT005 description: Message describing the error. fields: type: object nullable: true description: |- Structure with important fields for the connector. This structure is only returned if the response is successful. Includes the following fields: `mainOrderId`: String with the order's ID inside the main seller account in VTEX. `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: - `allowFranchises` field set to `true` when integrating the order - `SLA` chosen for the order is from a franchise account. properties: fields: type: object title: fields required: - mainOrderId properties: mainOrderId: type: string title: The mainOrderId Schema description: String with the order’s ID inside the main seller account in VTEX. example: MKP-123456789 franchiseOrderId: type: string title: The franchiseOrderId Schema 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' example: mainOrderId: MKP-123456789 franchiseOrderId: '432874921387409182347' example: franchiseOrderId: '38475934875' message: type: string description: String with a message explaining the code returned in the response. example: The order was integrated into VTEX successfully example: marketplaceOrderId: 7e62fcd3-827b-400d-be8a-f050a79c4976 accountName: code: SOI003 flow: ApproveOrder success: true operationId: errors: fields: message: Order successfully enqueued securitySchemes: appKey: type: apiKey in: header name: X-VTEX-API-AppKey appToken: type: apiKey in: header name: X-VTEX-API-AppToken tags: - name: External Marketplace