v1

latestOpenAPI 3.0.02026-07-141525155.4 KB

External Marketplace

Place fulfillment order

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.

If you plan to integrate external orders with possible Price divergence be mindful of the isCreatedAsync request body field.

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.

post/{accountName}.{environment}.com.br/api/fulfillment/pvt/orders

Path parameters

accountNamestring required

Name of the VTEX account. Used as part of the URL.

environmentstring required

Environment to be used. It is passed as part of the URL.

Query parameters

scstring

Example:1

Sales channel.

affiliateIdstring required

Example:MKP

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.

Headers

Content-Typestring required

Type of the content being sent.

Acceptstring required

HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.

Request body

isCreatedAsyncboolean

Indicates whether an order is created. It must be true if an order is being placed with Price divergence, otherwise the request will not work.

marketplaceOrderIdstring required

ID of the order in the marketplace.

marketplacePaymentValueinteger required

Value of the payment made to the marketplace.

marketplaceServicesEndpointstring required

Endpoint provided by the marketplace for post purchase communication. Should be an URL, containing protocol, host, path and query string (in case it applies).

openTextFieldstring

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

paymentDataobject nullable

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.

Example request

{
  "clientProfileData": {
    "corporateDocument": "12345678000100",
    "corporateName": "company-name",
    "corporatePhone": "+551100988887777",
    "document": "123456789",
    "documentType": "cpf",
    "email": "customer@examplemail.com",
    "firstName": "first-name",
    "lastName": "last-name",
    "phone": "+55110988887777",
    "stateInscription": "12345678",
    "tradeName": "trade-name"
  },
  "items": [
    {
      "id": "123456789",
      "quantity": 1,
      "seller": "1"
    }
  ],
  "marketingData": {
    "utmCampaign": "Black friday",
    "utmMedium": "CPC",
    "utmSource": "Facebook",
    "utmiCampaign": "utmi_campaign-exmaple",
    "utmiPage": "utmi_page-example",
    "utmiPart": "utmi_part-exmaple"
  },
  "marketplaceOrderId": "123456789",
  "marketplacePaymentValue": 100,
  "marketplaceServicesEndpoint": "https://exampleseller.marketplaceservices.com",
  "openTextField": "open-text-example",
  "shippingData": {
    "address": {
      "addressId": "Home",
      "addressType": "residential",
      "city": "Rio de Janeiro",
      "complement": "3rd floor",
      "country": "BRA",
      "geoCoordinates": [
        "00.00000"
      ],
      "neighborhood": "Botafogo",
      "number": "300",
      "postalCode": "12345000",
      "receiverName": "receiver-name",
      "reference": "Grey building",
      "state": "Rio de Janeiro",
      "street": "Praia de Botafogo"
    },
    "logisticsInfo": [
      {
        "deliveryWindow": {
          "endDateUtc": "2021-07-13T23:59:59+00:00",
          "startDateUtc": "2021-07-13T00:00:00+00:00"
        },
        "lockTTL": "8d",
        "price": 1099,
        "selectedSla": "Express",
        "shippingEstimate": "7d"
      }
    ],
    "updateStatus": "updated"
  }
}

v1