Sign in

v1

latestOpenAPI 3.0.02026-07-141525155.4 KB
External Seller

Order placement

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.

The marketplace will send information such as the items contained in the cart, the client’s profile data, the shipping data, and the payment data. With all that, the seller will be able to create the order in their own store.

post/{fulfillmentEndpoint}/pvt/orders

Path parameters

fulfillmentEndpointstring required
Example:https://marketplaceexample.externalseller.com

This is the fulfillment endpoint registered for each specific external seller in the seller management section of VTEX's admin panel.

Headers

content-lengthstring required
Example:2183

Length of the request body.

authorizationstring required
Example:VTEX key="appKey" token="appToken"

Indicates authorization.

x-vtex-api-appkeystring required
Example:appKey

VTEX API app key.

x-vtex-api-apptokenstring required
Example:appToken

VTEX API app token.

acceptstring required
Example:application/json

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

accept-encondingstring required
Example:gzip, deflate

Indicates the types of response enconding the client can understand.

x-vtex-operation-idstring required
Example:8032114b-63e9-4e64-b30c-f7afcf676d7a

VTEX operation ID.

x-forwarded-protostring required
Example:https

Determines the protocol used by the client in the request.

x-forwarded-forstring required
Example:179.35.30.186, 130.176.35.67, 172.16.247.49

Identifies the originating IP address of the HTTP client.

x-vtex-cache-client-bypassstring required
Example:1

VTEX cache client bypass.

content-typestring required
Example:application/json

Describes the type of the content being sent.

traceparentstring required
Example:00-083c0ca18bc8d94183f333809a70cd64-bf5e9a641e230540-00

Identifies the incoming request in a tracing system.

Request body

marketplaceOrderIdstring

Identifies the order in the marketplace.

marketplacePaymentValueinteger

Amount that the marketplace agrees to pay to the seller. The last two digits are the cents. For example, $24.99 is represented 2499.

marketplaceServicesEndpointstring

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 operations in external marketplaces.

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": [
    {
      "bundleItems": [
        {
          "id": 7436,
          "name": "name",
          "price": 10,
          "type": "type"
        }
      ],
      "id": "123456789abc",
      "itemsAttachment": [
        {
          "content": "content-example",
          "name": "name-example"
        }
      ],
      "measurementUnit": "g",
      "price": 2499,
      "priceTags": [
        {
          "identifier": "1234abc-5678b-1234c",
          "name": "discount@name-1234abc-5678b-1234c",
          "rawValue": -12,
          "value": -1200
        }
      ],
      "quantity": 1,
      "seller": "seller-example",
      "unitMultiplier": 1
    }
  ],
  "marketingData": {
    "utmCampaign": "Black friday",
    "utmMedium": "CPC",
    "utmSource": "Facebook",
    "utmiCampaign": "utmi_campaign-exmaple",
    "utmiPage": "utmi_page-example",
    "utmiPart": "utmi_part-exmaple"
  },
  "marketplaceOrderId": "1138342255777-01",
  "marketplacePaymentValue": 2499,
  "marketplaceServicesEndpoint": "https://marketplaceservicesendpoint.myvtex.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": "12345-000",
      "receiverName": "receiver-name",
      "reference": "Grey building",
      "state": "Rio de Janeiro",
      "street": "Praia de Botafogo"
    },
    "logisticsInfo": [
      {
        "deliveryWindow": {
          "endDateUtc": "2016-04-20T12:00:00+00:00",
          "listPrice": 10,
          "startDateUtc": "2016-04-20T08:00:00+00:00"
        },
        "lockTTL": "8d",
        "price": 1099,
        "selectedSla": "Express",
        "shippingEstimate": "7d"
      }
    ],
    "updateStatus": "updated"
  }
}

Response

OK