---
title: "Order placement"
method: POST
path: "/{fulfillmentEndpoint}/pvt/orders"
tags: ["External Seller"]
---

# Order placement

`POST /{fulfillmentEndpoint}/pvt/orders`

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.

## Path parameters

- `fulfillmentEndpoint` string, required

## Headers

- `content-length` string, required
- `authorization` string, required
- `x-vtex-api-appkey` string, required
- `x-vtex-api-apptoken` string, required
- `accept` string, required
- `accept-enconding` string, required
- `x-vtex-operation-id` string, required
- `x-forwarded-proto` string, required
- `x-forwarded-for` string, required
- `x-vtex-cache-client-bypass` string, required
- `content-type` string, required
- `traceparent` string, required

## Request body

- OrderPlacement
  - `clientProfileData` object — Customer's profile information.
    - `corporateDocument` string, nullable — Corporate document, if the customer is a legal entity.
    - `corporateName` string, nullable — Company name, if the customer is a legal entity.
    - `corporatePhone` string, nullable — Corporate phone number, if the customer is a legal entity.
    - `document` string, required — Document number informed by the customer.
    - `documentType` string, required — Type of the document informed by the customer.
    - `email` string, required — Customer's email address.
    - `firstName` string, required — Customer's first name.
    - `isCorporate` boolean, nullable, required — `true` if the customer is a legal entity.
    - `lastName` string, required — Customer's last name.
    - `phone` string — Customer's phone number.
    - `stateInscription` string, nullable — State inscription, if the customer is a legal entity.
    - `tradeName` string, nullable — Trade name, if the customer is a legal entity.
  - `items` object[] — Array of objects containing data about each SKU in the cart.
    - `attachments` unknown[] — Array containing information on attachments.
      - unknown
    - `bundleItems` BundleItemsItem[] — Information on services sold along with the SKU. Example: a gift package.
      - `id` integer — Service identifier.
      - `name` string — Service name.
      - `price` integer — Service price. The last two digits are the cents.
      - `type` string — Service type.
    - `commission` integer — Comission.
    - `freightCommission` integer — Freight comission.
    - `id` string — SKU ID.
    - `isGift` boolean — `true` if the item is a gift.
    - `itemsAttachment` ItemAttachment[] — Attachments sold with the SKU.
      - `content` string — Content referring to the customization requested by the customer.
      - `name` string — Attachment name.
    - `measurementUnit` string — SKU measurement unit.
    - `price` integer — SKU price. The last two digits are the cents. For example, $24.99 is represented 2499.
    - `priceTags` object[] — 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.
      - `identifier` string — Price tag identifier.
      - `isPercentual` boolean — `true` if price tag value is applied through a percentage.
      - `name` string — Price tag name.
      - `rawValue` integer — Price tag value.
      - `value` integer — Price tag raw value.
    - `quantity` integer — Quantity of the item.
    - `seller` string — ID of the seller registered in VTEX.
    - `unitMultiplier` integer — SKU unit multiplier.
  - `marketingData` object — Marketing tracking data. If the order has no tracking data, the value will be `null`.
    - `utmCampaign` string — UTM campaign
    - `utmMedium` string — UTM medium.
    - `utmSource` string — UTM source.
    - `utmiCampaign` string — utmi_campaign (internal utm)
    - `utmiPage` string — utmi_page (internal utm)
    - `utmiPart` string — utmi_part (internal utm)
  - `marketplaceOrderId` string — Identifies the order in the marketplace.
  - `marketplacePaymentValue` integer — Amount that the marketplace agrees to pay to the seller. The last two digits are the cents. For example, $24.99 is represented 2499.
  - `marketplaceServicesEndpoint` string — Endpoint sent by VTEX to the seller, that will be used to send the invoice and tracking data to the marketplace. This endpoint will also be used in [change order in Multilevel Omnichannel Inventory](https://developers.vtex.com/docs/guides/change-orders-multilevel-omnichannel-inventory-external-marketplaces#implementators) operations in external marketplaces.
  - `openTextField` string — 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)
  - `paymentData` object, 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.
  - `shippingData` object — Shipping information.
    - `address` object — Shipping address.
      - `addressId` string — Address ID.
      - `addressType` string, required — Type of address. For example, `Residential` or `Pickup`, among others.
      - `city` string, required — City of the shipping address.
      - `complement` string — Complement to the shipping address in case it applies.
      - `country` string, required — Three letter ISO code of the country of the shipping address.
      - `geoCoordinates` string[] — Array with two strings with geocoordinates, first latitude, then longitude.
      - `neighborhood` string, required — Neighborhood of the shipping address.
      - `number` string, required — Number of the building, house or apartment in the shipping address.
      - `postalCode` string, required — Postal Code.
      - `receiverName` string, required — Name of the person who is going to receive the order.
      - `reference` string — Complement that might help locate the shipping address more precisely in case of delivery.
      - `state` string, required — State of the shipping address.
      - `street` string, required — Street of the shipping address.
    - `logisticsInfo` object[] — Array of objects containing logistics information of each item.
      - `deliveryWindow` object — Scheduled delivery window information, in case it applies to the item.
        - `endDateUtc` string — Scheduled delivery window end date in UTC.
        - `listPrice` number — Scheduled delivery window list price.
        - `startDateUtc` string — Scheduled delivery window start date in UTC.
      - `itemIndex` integer, required — Index of the item in the `items` array, starting from 0.
      - `lockTTL` string — Logistics reservation waiting time.
      - `price` integer, required — Shipping price for the item. Does not account for the whole order's shipping price.
      - `selectedSla` string, required — Selected shipping option
      - `shippingEstimate` string — Estimated time until delivery for the item.
    - `updateStatus` string — Indicate whether this object's information is up to date according to the order's items. An order can not be placed if `"outdated"`

## Response `200`

OK

---

[API](https://skmtc.net/vtex/apis/marketplace-protocol.md) · [All operations](https://skmtc.net/vtex/apis/marketplace-protocol/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vtex/marketplace-protocol/versions/73bf2ca74b15/schema)