[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides orders overview in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/getting-started)

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/catalog-overview)

[Marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/marketplace-overview)

[Orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview)

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/checkout-overview)

[Payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/payments-overview)

[Fulfillment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/fulfillment)

[Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/search-overview)

[Pricing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/pricing-overview)

[Promotions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/promotions-overview)

[Subscriptions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/subscriptions)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/master-data)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/getting-started)

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/catalog-overview)

[Marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/marketplace-overview)

[Orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview)

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/checkout-overview)

[Payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/payments-overview)

[Fulfillment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/fulfillment)

[Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/search-overview)

[Pricing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/pricing-overview)

[Promotions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/promotions-overview)

[Subscriptions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/subscriptions)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/master-data)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides)

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/getting-started)

[Orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview)

Orders

> **Help us improve our documentation!** Tell us about your experience with this article by completing [this form](https://read.calvincode.net/reader?url=https://forms.gle/fQoELRA1yfKDqmAb8).

This overview article covers the VTEX Order Management System (OMS), including relevant links from our developer documentation. In the following sections, you will find information about setting up and managing your orders, creating order integrations with external partners, and configuring optional settings.

### Importing orders from an ERP or Back office

If your store has an ERP integration or another integration for managing orders, you will need to create an integration with the VTEX platform. The links below provide an overview of the order integration flow between a back-office system and a VTEX store.

* [Back office (ERP/PIM/WMS)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/erp-integration-guide)
* [Set up order integration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/erp-integration-set-up-order-integration)
* [Set up order processing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/erp-integration-set-up-order-processing)
* [Change order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/change-order)
* [FAQ: ERP Integration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faq-erp-integration)

## Understanding order flow types

The order flow describes the status, possible flows, and actions throughout the life cycle of an order. On VTEX, there are four [order flow types](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials%5F196):

### Marketplace flow

The marketplace order flow is only visible to the store responsible for the sale.

![{"base64":"  ","img":{"width":9483,"height":5166,"type":"jpg","mime":"image/jpeg","wUnits":"px","hUnits":"px","length":767240,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/orders-overview-0.jpg"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/orders-overview-0.jpg)

### Seller flow

The seller order flow is only visible to the store responsible for handling the order.

![{"base64":"  ","img":{"width":6258,"height":2556,"type":"jpg","mime":"image/jpeg","wUnits":"px","hUnits":"px","length":321573,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/orders-overview-1.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/orders-overview-1.png)

### Complete flow

The complete order flow is only visible to the store responsible for the sale and delivery. In this case, the store acts both as seller and marketplace.

![{"base64":"  ","img":{"width":7611,"height":2102,"type":"jpg","mime":"image/jpeg","wUnits":"px","hUnits":"px","length":320548,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/orders-overview-2.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/orders-overview-2.png)

### Chain flow

The chain order flow is visible to the store acting as an intermediary between the marketplace and the seller. This flow is similar to the marketplace flow. However, the payment is only made to the marketplace, not to the store that acts as a chain. This flow is followed in [Multilevel Omnichannel Inventory](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/multilevel-omnichannel-inventory) sales situations.

![{"base64":"  ","img":{"width":5419,"height":2952,"type":"jpg","mime":"image/jpeg","wUnits":"px","hUnits":"px","length":338064,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/orders-overview-3.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/orders-overview-3.png)

## Understanding order statuses

In the [My Account](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/how-my-account-works--2BQ3GiqhqGJTXsWVuio3Xh%23view-order-details) menu, every order shows a timeline of five stages, indicating the order flow. Each stage has several triggers that change the order status accordingly. You can see the triggers, their descriptions, and the order statuses they generate in My Account. Stages 1, 2, and 3 are the same for every order; however, Stages 4 and 5 have different triggers and outcomes depending on whether it's a pickup or a delivery order.

> An order is considered for pickup when its `selectedDeliveryChannel` field contains the value `pickup-in-point`. You can retrieve this information using the [Get order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23get-/api/oms/pvt/orders/-orderId-) endpoint.

### Stage 1

The order is created and starts in this stage.

| Trigger                        | Description                                                                                | My Account status |
| ------------------------------ | ------------------------------------------------------------------------------------------------------ | ----------------- |
| order.progress.confirmOrder    | Workflow has not been created due to an error with the payment gateway.                                | Place order       |
| order.progress.confirmingOrder | The order's API status is one of the following: order-created, order-completed, or on-order-completed. | Placing order     |
| order.progress.orderConfirmed  | The order's API status is none of the above, i.e., the order is in a later status.                     | Order placed      |

### Stage 2

The order reaches this stage after it is placed.

| Trigger                         | Description                                                                        | My Account status |
| ------------------------------- | ---------------------------------------------------------------------------------- | ----------------- |
| order.progress.approvePayment   | The order's API status is a Stage 1 status.                                        | Approve payment   |
| order.progress.approvingPayment | The order's API status is payment-pending or approve-payment.                      | Approving payment |
| order.progress.paymentApproved  | The order's API status is none of the above, i.e., the order is in a later status. | Payment approved  |

### Stage 3

The order reaches this stage after its payment is approved.

| Trigger                         | Description                                                                                | My Account status |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| order.progress.handleShipping   | The order's API status is a Stage 1 or 2 status.                                                                                | Handle order      |
| order.progress.handlingShipping | The order's API status is one of the following: window-to-cancel, payment-approved, ready-for-handling, authorize-fulfillment, release-to-fulfillment, handling, or invoice. | Handling order    |
| order.progress.shippingHandled  | The order's API status is none of the above, i.e., the order is in a later status.                                                                                | Package handled   |

### Stage 4

The order reaches this stage after it is handled.

#### Orders for pickup

| Trigger                           | Description                                                                     | My Account status        |
| --------------------------------- | ------------------------------------------------------------------------------- | ------------------------ |
| order.progress.deliverToPickup    | The order's API status is a stage 1, 2, or 3 status.                            | Ship to pickup point     |
| order.progress.deliveringToPickup | The order's API status is invoiced.                                             | Shipping to pickup point |
| order.progress.deliveredToPickup  | The order will remain in this status until the rules for stage 5 are completed. | Shipped to pickup point  |

#### Orders with delivery

| Trigger                         | Description                                                                     | My Account status     |
| ------------------------------- | ------------------------------------------------------------------------------- | --------------------- |
| order.progress.deliverToCarrier | The order's API status is a status in stage 1, 2, or 3.                         | Deliver to carrier    |
| order.progress.delivering       | The order's API status is invoiced.                                             | Delivering to carrier |
| order.progress.delivered        | The order will remain in this status until the rules for stage 5 are completed. | Delivered to carrier  |

### Stage 5

The order reaches this stage when it has been invoiced.

#### Orders for pickup

| Trigger                      | Description                                                                            | My Account status |
| ---------------------------- | -------------------------------------------------------------------------------------- | ----------------- |
| order.progress.pickup        | Order status when the field shippingEstimateDate has a future estimate date.           | Pickup            |
| order.state.ready-for-pickup | Order status when the field shippingEstimateDate is empty or has a past estimate date. | Ready for pickup  |
| order.state.pickedUp         | Order status when the field finished within the object courierStatus is set to true.   | Picked up         |

#### Orders with delivery

| Trigger                 | Description                                                                       | My Account status |
| ----------------------- | --------------------------------------------------------------------------------- | ----------------- |
| order.progress.ship     | Order status when the array Data within the object courierStatus is empty.        | Ship order        |
| order.progress.shipping | Order status when the array Data within the object courierStatus has been filled. | Shipping order    |
| order.progress.shipped  | Order status when the array Data within the object courierStatus is set to true.  | Order shipped     |

## Creating an order integration

In the following sections, you will learn how to build order integrations with Feed and Hook. For example, this can be useful for developing an integration between your store ERP and the VTEX platform.

> We strongly recommend you to create an order integration using the [Orders Feed v3](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed), instead of using the List orders API request or external services. If you already use an integration based on the API request, you should migrate to using the Feed. Keep in mind that this means changing the integration flow. To learn how to implement this change, see the [Set up order integration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/erp-integration-set-up-order-integration).

### Feed v.3

The Orders feed is a list of order updates, meaning that an order status update will be included as a new item in the feed whenever there is an event in an order.

* [Feed v3 Guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed)
* [Get feed configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23get-/api/orders/feed/config)
* [Create or update feed configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/orders/feed/config)
* [Delete feed configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/feedconfigurationdelete)
* [Retrieve feed items](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23get-/api/orders/feed)
* [Commit feed items](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/orders/feed)
* [Test JSONata expression](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/orders/expressions/jsonata)

### Hook

Hook works as a complement to Feed, because it allows an integration to consume order updates data by sending items to a URL provided by the user in the Hook configuration.

* [Get hook configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/gethookconfiguration)
* [Create or update hook configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/hookconfiguration)
* [Delete hook configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/deletehookconfiguration)

## Managing orders

There are several actions a VTEX store can perform on orders. In the following sections, you will find the main actions related to a store’s order management routine.

> This module may process personal or sensitive information. Learn more about how VTEX handles data privacy at our [Data privacy](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/data-privacy) guide.

### Placing an order

Placing an order involves the Order Management module and [Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/checkout-overview). There are different paths to create orders. For more information about placing orders, see the links below.

* [Place order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/checkout-api%23put-/api/checkout/pub/orders)
* [Place order from an existing cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/placeorderfromexistingorderform)
* [Process order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/checkout-api%23post-/api/checkout/pub/gatewayCallback/-orderGroup-)
* [Create a regular order using the Checkout API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/create-a-regular-order-using-the-checkout-api)

> The [orderForm](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orderform-fields) is the main object processed by the [Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/checkout-overview) and it stores a lot of contextual information about an order. The orderForm fields will be present in most of OMS's API calls.

### Retrieving order’s details

> You can only access information from orders created in the last two years, and that same period is valid for customers through [My Account](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/how-my-account-works--2BQ3GiqhqGJTXsWVuio3Xh).

You can fetch information about orders in multiple ways and about specific topics. To learn more about retrieving order content, see the links below.

#### Orders

* [Get order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23get-/api/oms/pvt/orders/-orderId-)
* [List orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23get-/api/oms/pvt/orders)

#### Conversation

* [Retrieve order conversation](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/getconversation)

#### User

* [Retrieve user's orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/userorderslist)
* [Retrieve user order details](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/userorderdetails)

#### Payment

* [Retrieve payment transaction](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/getpaymenttransaction)

#### Marketplace

* [Fetching marketplace information with the Orders API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-marketplace-data-orders-api)
* [Fetching payment details from a Mercado Libre order with Orders API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/get-payment-data-mercado-libre-orders-api)

### Changing an order status

Every order has a life cycle registered as an [order flow](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials%5F196), which describes the order status, options, and updates. For more information, see the links below.

* [Start handling order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/oms/pvt/orders/-orderId-/start-handling)
* [Cancel order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/oms/pvt/orders/-orderId-/cancel)

### Changing an order

Changing orders is a feature that allows your store to edit the items or prices of an order. For example, this allows you to handle eventual changes due to customer mistakes or product unavailability. To learn more, see the links below.

* [Change order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/change-order)
* [Register change on order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/oms/pvt/orders/-orderId-/changes)

### Changing seller

Another seller can be selected to fulfill a given order after the original seller canceled it. The period when this can be done is called the change seller window. You can use the endpoints below for this.

* [Get window to change seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23get-/api/checkout/pvt/configuration/window-to-change-seller)
* [Update window to change seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/checkout/pvt/configuration/window-to-change-seller)

### Sending payment notification

For your payment provider to notify the Order Management System that the payment of a given order is completed, use the [Send payment notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/oms/pvt/orders/-orderId-/payments/-paymentId-/payment-notification) endpoint.

If your store receives payments outside the VTEX platform, such as cash or notes payable, it must call this endpoint to notify the OMS, so the order can follow its flow and be fulfilled.

> The endpoint [Send payment notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/oms/pvt/orders/-orderId-/payments/-paymentId-/payment-notification) must be called only after the order payment has been approved. The store might not receive the payment if there is an issue with the settlement and the endpoint has already been called.

### Invoicing an order

When you [invoice an order](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/orders--2xkTisx4SXOWXQel8Jg8sa/2WgQrlHTyVo4hLjhUs1LMT), its status in the [order flow](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials%5F196) changes to Invoiced, which means the order was successfully completed. After an order is invoiced, you can no longer modify its status, except when you want to send a return invoice.

In that case, the [Order invoice notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/oms/pvt/orders/-orderId-/invoice) endpoint must be called, and instead of having the field `type` value defined as Output, it will be Input.

* [Order invoice notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/oms/pvt/orders/-orderId-/invoice)
* [Update order's partial invoice (send tracking number)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23patch-/api/oms/pvt/orders/-orderId-/invoice/-invoiceNumber-)
* [Adding a second address for invoicing an order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/adding-a-second-address-to-the-order)
* [Formatting order invoicing time via API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time)

### Tracking an order

Every order has a tracking number that allows you to keep track of its status in the [order flow](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials%5F196). To send a tracking event to an order with a tracking number, use the [Update order's partial invoice](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/updatepartialinvoicesendtrackingnumber) endpoint.

If you want to add a tracking number and URL to an order invoice, use the [Update order's partial invoice](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/updatepartialinvoicesendtrackingnumber) endpoint.

## Integrating with the Multilevel Omnichannel Inventory

[Multilevel Omnichannel Inventory](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/multilevel-omnichannel-inventory) is the VTEX setting that allows the inventory of [franchises](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/what-is-a-franchise-account--kWQC6RkFSCUFGgY5gSjdl) or [white label sellers](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/white-label-seller--5orlGHyDHGAYciQ64oEgKa) to be sold in marketplaces the main account is connected to.

In other words, the feature allows VTEX sellers to sell products from its franchises or white label sellers in a marketplace, without the need to set up the integration with the desired marketplace. For marketplaces, this means selling products from their direct sellers and also physical stores and white label sellers associated with those sellers in a scalable way.

> For more information, see the article [Multilevel Omnichannel Inventory](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/multilevel-omnichannel-inventory--7M1xyCZWUyCB7PcjNtOyw4).

## Integrating orders from an external marketplace

A VTEX store can act as both a [seller](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/configuring-a-seller-on-vtex-marketplace--6g045OkRSjNpqhkExbQRlP) and a [marketplace](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/configuring-vtex-marketplace--7splyp5MqIyt2Iyz5jsNzb) in relation to another VTEX store or an external partner. If you are an [external marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/external-marketplace-integration-guide) that wants to integrate with VTEX sellers, see the links below to learn how to develop a custom connector to integrate with the VTEX architecture and seller orders.

* [Order Integration overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-orders)
* [New Order Integration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-collect-orders)
* [Update Order Status](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-update-order-status)
* [How to update the status of a canceled order on VTEX](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-marketplace-integration-canceled-orders)

## Adding optional configurations

There are additional configurations available for you to manage your store orders. This allows you to take advantage of other VTEX features, such as [VTEX Sales App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/how-to-customize-vtex-sales-app), [VTEX DO](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/vtex-do-interface--7KMbRL4OslN8DTX9oiuCiu), [B2B](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/b2b-overview--5vb9SNXhX2bZnkpAh7ADdC), and [Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/master-data).

### VTEX Sales App

[Enable partial cancellation for Debit or Credit Direct sales](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/enable-partial-cancellation)

### VTEX DO

* [Create Note](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/newnote)
* [Get Notes by orderId](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/getnotesbyorderid)
* [Retrieve Note](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/getnote)
* [Create Task](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/newtask)
* [List tasks](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/listtasksbyassignee)
* [Retrieve Task](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/gettask)
* [Update Task](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/vtex-do-api%23put-/tasks/-taskId-)
* [Add Comment on a Task](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/vtex-do-api%23post-/tasks/-taskId-/comments)

### B2B

* [B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-suite)

### Master Data

* [Using Master Data v2 triggers to interact with orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/using-master-data-v2-triggers-to-interact-with-orders)

Contributors

4

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F77300325%3Fv%3D4%26w=64%26q=75)](https://github.com/Isabella-Veloso)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F170467615%3Fv%3D4%26w=64%26q=75)](https://github.com/mariananantua)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F77292838%3Fv%3D4%26w=64%26q=75)](https://github.com/julia-rabello)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F106821144%3Fv%3D4%26w=64%26q=75)](https://github.com/GeorgeLimaDev)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Getting-Started/orders-overview.md)

[Marketplace« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview//docs/guides/marketplace-overview)[CheckoutNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview//docs/guides/checkout-overview)

Contributors

4

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F77300325%3Fv%3D4%26w=64%26q=75)](https://github.com/Isabella-Veloso)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F170467615%3Fv%3D4%26w=64%26q=75)](https://github.com/mariananantua)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F77292838%3Fv%3D4%26w=64%26q=75)](https://github.com/julia-rabello)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F106821144%3Fv%3D4%26w=64%26q=75)](https://github.com/GeorgeLimaDev)

ON THIS PAGE

[Understanding order flow types](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23understanding-order-flow-types)

[Marketplace flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23marketplace-flow)[Seller flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23seller-flow)[Complete flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23complete-flow)[Chain flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23chain-flow)

[Understanding order statuses](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23understanding-order-statuses)

[Stage 1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23stage-1)[Stage 2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23stage-2)[Stage 3](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23stage-3)[Stage 4](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23stage-4)[Stage 5](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23stage-5)

[Creating an order integration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23creating-an-order-integration)

[Feed v.3](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23feed-v3)[Hook](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23hook)

[Managing orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23managing-orders)

[Placing an order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23placing-an-order)[Retrieving order’s details](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23retrieving-orders-details)[Changing an order status](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23changing-an-order-status)[Changing an order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23changing-an-order)[Changing seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23changing-seller)[Sending payment notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23sending-payment-notification)[Invoicing an order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23invoicing-an-order)[Tracking an order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23tracking-an-order)

[Integrating with the Multilevel Omnichannel Inventory](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23integrating-with-the-multilevel-omnichannel-inventory)

[Integrating orders from an external marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23integrating-orders-from-an-external-marketplace)

[Adding optional configurations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23adding-optional-configurations)

[VTEX Sales App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23vtex-sales-app)[VTEX DO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23vtex-do)[B2B](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23b2b)[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23master-data)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Getting-Started/orders-overview.md)

Copy page

On this page

ON THIS PAGE

[Understanding order flow types](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23understanding-order-flow-types)

[Marketplace flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23marketplace-flow)[Seller flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23seller-flow)[Complete flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23complete-flow)[Chain flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23chain-flow)

[Understanding order statuses](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23understanding-order-statuses)

[Stage 1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23stage-1)[Stage 2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23stage-2)[Stage 3](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23stage-3)[Stage 4](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23stage-4)[Stage 5](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23stage-5)

[Creating an order integration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23creating-an-order-integration)

[Feed v.3](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23feed-v3)[Hook](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23hook)

[Managing orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23managing-orders)

[Placing an order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23placing-an-order)[Retrieving order’s details](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23retrieving-orders-details)[Changing an order status](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23changing-an-order-status)[Changing an order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23changing-an-order)[Changing seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23changing-seller)[Sending payment notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23sending-payment-notification)[Invoicing an order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23invoicing-an-order)[Tracking an order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23tracking-an-order)

[Integrating with the Multilevel Omnichannel Inventory](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23integrating-with-the-multilevel-omnichannel-inventory)

[Integrating orders from an external marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23integrating-orders-from-an-external-marketplace)

[Adding optional configurations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23adding-optional-configurations)

[VTEX Sales App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23vtex-sales-app)[VTEX DO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23vtex-do)[B2B](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23b2b)[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview/docs/guides/orders-overview%23master-data)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides add marketing information to the cart in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/checkout-api-overview)

[Custom Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/custom-data-1)

[Customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/customization)

[Discounts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/discounts)

[Features](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/features)

[Order Placement](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/orders-2)

[Security](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/checkout-security)

[Shopping Cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/shopping-cart-section-api-quick-start-guides)

[Cart Attachments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/cart-attachments-section-api-quick-start-guides)

[Getting a customer profile by email](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/getting-a-customer-profile-by-email)

[Adding customer profile information to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-customer-profile-information-to-the-cart)

[Add shipping address and select delivery option](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-shipping-address-and-delivery-option-to-the-cart)

[Adding customer preferences to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-customer-preferences-to-the-cart)

[Adding marketing information to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-marketing-information-to-the-cart)

[Add cart items](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-cart-items)

[Adding payment information to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/adding-payment-information-to-the-cart)

[Adding merchant context information to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-merchant-context-information-to-the-cart)

[Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/configuration-section-api-quick-start-guides)

[Fulfillment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/fulfillment-checkout-section-api-quick-start-guides)

[Region](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/region-section-api-quick-start-guides)

[Checkout error codes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/checkout-error-codes)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/master-data)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/checkout-api-overview)

[Custom Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/custom-data-1)

[Customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/customization)

[Discounts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/discounts)

[Features](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/features)

[Order Placement](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/orders-2)

[Security](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/checkout-security)

[Shopping Cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/shopping-cart-section-api-quick-start-guides)

[Cart Attachments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/cart-attachments-section-api-quick-start-guides)

[Getting a customer profile by email](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/getting-a-customer-profile-by-email)

[Adding customer profile information to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-customer-profile-information-to-the-cart)

[Add shipping address and select delivery option](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-shipping-address-and-delivery-option-to-the-cart)

[Adding customer preferences to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-customer-preferences-to-the-cart)

[Adding marketing information to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-marketing-information-to-the-cart)

[Add cart items](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-cart-items)

[Adding payment information to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/adding-payment-information-to-the-cart)

[Adding merchant context information to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-merchant-context-information-to-the-cart)

[Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/configuration-section-api-quick-start-guides)

[Fulfillment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/fulfillment-checkout-section-api-quick-start-guides)

[Region](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/region-section-api-quick-start-guides)

[Checkout error codes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/checkout-error-codes)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/master-data)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides)

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/checkout-api-overview)

[Cart Attachments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/cart-attachments-section-api-quick-start-guides)

[Adding marketing information to the cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-marketing-information-to-the-cart)

Adding marketing information to the cart

The shopping cart gathers information on the products the customer chooses while browsing a store, such as prices, shipping costs, payment methods, delivery methods, etc. This data may include item prices, shipping value, payment, and delivery methods, among others.

This guide will describe how to add marketing data information to the shopping cart via API. For more information about UTMs, read [What are utm\_source, utm\_campaign, and utm\_medium](https://read.calvincode.net/reader?url=https://help.vtex.com/tutorial/what-are-utm-source-utm-campaign-and-utm-medium).

## Getting shopping cart information

The first step is to get the `orderFormId` of the shopping cart to which you want to add the marketing information. For more information, read the [Getting cart information by ID](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/get-cart-information-by-id) guide.

## Adding marketing information to the shopping cart

To add marketing information to the shopping cart, you need to use the [Add marketing data](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/addmarketingdata) endpoint. In this request, you must send the `orderFormId` through the URL address, as shown in the example below:

`https://{accountName}.{environment.com.br}/api/checkout/pub/orderForm/ede846222cd44046ba6c638442c3505a/attachments/marketingData`

Additionally, you must send the request body containing the following marketing information:

* `coupon`: Coupon code to apply to the cart. Use the [cart simulation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/checkout-api%23post-/api/checkout/pub/orderForms/simulation) request to check which coupons can be applied before placing the order.
* `marketingTags`: Marketing tags.
* `utmSource`: Traffic source (e.g. Facebook, Google).
* `utmMedium`: Advertising or marketing media (e.g. banner, CPC).
* `utmCampaign`: Campaign name (e.g. Christmas, launch, promo01).
* `utmiPage`: utmi\_page (internal utm).
* `utmiPart`: utmi\_part (internal utm).
* `utmiCampaign`: utmi\_campaign (internal utm).

See a request body example below:

`1

{

2

 "coupon": "free-shipping",

3

 "marketingTags": [

4

 "tag1",

5

 "tag2"

6

 ],

7

 "utmSource": "Facebook",

8

 "utmMedium": "CPC",

9

 "utmCampaign": "Black Friday",

10

 "utmiPage": "utmi_page-example",

11

 "utmiPart": "utmi_part-example",

12

 "utmiCampaign": "utmi_campaign-example"

13

}

`

After sending the request, the endpoint will return the response body containing the client preferences information in the shopping cart, as in the example below:

`1

...

2

"marketingData": {

3

 "utmSource": "Facebook",

4

 "utmMedium": "CPC",

5

 "utmCampaign": "Black Friday",

6

 "utmipage": "utmi_page-example",

7

 "utmiPart": "utmi_part-exmaple",

8

 "utmiCampaign": "utmi_campaign-example",

9

 "coupon": "free-shipping",

10

 "marketingTags": [

11

 "tag1",

12

 "tag2"

13

 ]

14

 }

15

...

`

>  For more information on the meaning of each field available in the shopping cart, see the [orderForm](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orderform-fields) overview.

## Error codes

The following errors may appear as a message in the response body.

### 200 - OK

Despite the code `200`, which indicates the success of the request, if the `coupon` code sent is incorrect or unavailable, the following message will appear:

`1

...

2

"messages": [

3

 {

4

 "code": "couponNotFound",

5

 "text": "Coupon 34324 invalid",

6

 "status": "warning",

7

 "fields": {}

8

 }

9

 ]

10

...

`

### 400 - Bad Request

* `Message error example (code ORD002): "Invalid order form"`. The `orderFormId` information is not valid.

`1

{

2

 "fields": {},

3

 "error": {

4

 "code": "ORD002",

5

 "message": "Invalid order form",

6

 "exception": null

7

 },

8

 "operationId": "5d9f54e6-7db4-46d6-bca9-deeb278b8b98"

9

}

`

### 404 - Not Found

* `Message error example: "The requested URL was not found on the server"`: Check if the URL is correct.

`1

2

404 Not Found

3

The requested URL was not found on this server.

4

`

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F106821144%3Fv%3D4%26w=64%26q=75)](https://github.com/GeorgeLimaDev)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Checkout/cart-attachments-section-quick-start-guides/add-marketing-information-to-the-cart.md)

[Adding customer preferences to the cart« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart//docs/guides/add-customer-preferences-to-the-cart)[Add cart itemsNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart//docs/guides/add-cart-items)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F106821144%3Fv%3D4%26w=64%26q=75)](https://github.com/GeorgeLimaDev)

ON THIS PAGE

[Getting shopping cart information](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-marketing-information-to-the-cart%23getting-shopping-cart-information)

[Adding marketing information to the shopping cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-marketing-information-to-the-cart%23adding-marketing-information-to-the-shopping-cart)

[Error codes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-marketing-information-to-the-cart%23error-codes)

[200 - OK](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-marketing-information-to-the-cart%23200-ok)[400 - Bad Request](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-marketing-information-to-the-cart%23400-bad-request)[404 - Not Found](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-marketing-information-to-the-cart%23404-not-found)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Checkout/cart-attachments-section-quick-start-guides/add-marketing-information-to-the-cart.md)

Copy page

On this page

ON THIS PAGE

[Getting shopping cart information](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-marketing-information-to-the-cart%23getting-shopping-cart-information)

[Adding marketing information to the shopping cart](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-marketing-information-to-the-cart%23adding-marketing-information-to-the-shopping-cart)

[Error codes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-marketing-information-to-the-cart%23error-codes)

[200 - OK](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-marketing-information-to-the-cart%23200-ok)[400 - Bad Request](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-marketing-information-to-the-cart%23400-bad-request)[404 - Not Found](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/add-marketing-information-to-the-cart/docs/guides/add-marketing-information-to-the-cart%23404-not-found)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)