> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://mailchimp.com/developer/marketing/concepts/e-commerce/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://mailchimp.com/_mcp/server.

# E-Commerce

> How stores, customers, products, carts, and orders relate to each other in Mailchimp.

## The basics

Connecting an external store to your Mailchimp account gives Mailchimp a model of your commerce data: what you sell, who buys it, and what they have bought or left behind. That data is what drives [Mailchimp's e-commerce features](https://mailchimp.com/help/how-mailchimp-can-help-your-online-store/), including order notifications, abandoned cart automations, follow-ups, and product recommendations.

## How the pieces fit together

```
Store                   one connected storefront, tied to one audience
├── Customers           buyers, identified by email address
├── Products            items for sale
│   ├── Variants        the specific purchasable versions of a product
│   └── Images          product imagery
├── Carts               in-progress purchases
│   └── Cart lines      product variants in a cart
├── Orders              completed purchases
│   └── Order lines     product variants in an order
└── Promo rules         discounts a store offers
    └── Promo codes     the codes customers enter to claim a rule
```

**Stores** are the top-level e-commerce entity. Customers, products, carts, orders, and promo rules all exist inside the scope of a store, and nothing e-commerce exists outside one.

Each store is tied to one Mailchimp audience, so the people who buy from your store are contacts in that audience. A single audience can support multiple stores, but a store's audience is fixed once set.

**Customers** are the people who buy from a store. A customer is identified by email address, which is also how they map to a contact in the store's audience.

**Products** are the items a store sells. A product is a parent entity that holds one or more **variants**, the specific purchasable versions of it: a size, a color, an edition. Prices, SKUs, and inventory live on the variant, not the product.

**Carts** are in-progress purchases. A cart holds **cart lines**, each of which points at a product variant and a quantity. Carts are what abandoned cart automations run on; they don't become orders and they don't expire on their own.

**Orders** are completed purchases, holding **order lines** in the same shape as cart lines. Orders are the record of revenue, and they're what product recommendations and purchase-based automations are built from.

**Promo rules** are the discounts a store offers, and each one holds the **promo codes** customers enter to claim it.

> **Note**
>
> **Products come first**: a variant has to exist in a store before a cart line or order line can reference it. Adding products is the first step of any store sync, not a later one.

## Stores

Some store fields are always required, while others are only required in certain cases. The `domain` field, for example, is necessary to enable Connected Sites and Google Ads.

When [creating a new store](/marketing/api/ecommerce/create-store), the required store ID is client-defined; use whatever identifies that storefront in your own system. Each store must name the audience it belongs to by [`list_id`](/marketing/api/lists/list). After a store is created and tied to an audience, it cannot be connected to a different audience.

> **Note**
>
> **Note**: [Mailchimp Stores](https://mailchimp.com/features/online-store/) are automatically available in the Stores endpoints and their data is kept in sync in real time as transactions occur. All Mailchimp Stores and the data contained therein (e.g., products, orders, carts) should be considered read-only in the Marketing API; there is no need to create, update, or delete these records via the API.

## Customers

Like the store ID, the customer ID is client-defined. If your e-commerce setup assigns customer IDs, you can add customers to Mailchimp without a new ID string.

Because a customer is also a contact in the store's audience, adding one has an effect on audience membership. If a customer's email address is not already associated with an audience, it will be added with the subscription status determined by the `opt_in_status` parameter. An `opt_in_status` of `true` will result in a `subscribed` audience member; `false` will set the status to `transactional`. Updating the customer's `opt_in_status` from `false` to `true` will update the member's subscription status to `subscribed`. However, updating the `opt_in_status` from `true` to `false` will not change the subscription status.

> **Note**
>
> **Note**: Customers who have opted out of your Mailchimp audience will be added as transactional members. Although the `opt_in_status` parameter is present, it will not overwrite the status of a pre-existing contact.

Mailchimp also offers double opt-in, which includes an extra confirmation step to verify the customer's email address. For double opt-in emails to be sent properly, the contact's status must first be set to `transactional` and then to `pending`.

You'll need to make two requests:

1. Add the customer as a transactional contact by making a POST request to the [Customers endpoint](/marketing/api/ecommerce/list-store-customers) with a value of `false` for the `opt_in_status` field. (Sending a value of `true` would add them as a subscriber and opt them into marketing emails.)
2. Edit the contact by making a PATCH request to `lists/{list_id}/members/{subscriber_hash}` with a value of `pending` for the `status` field.

## Products

A product must exist in a store before it can be added to a cart or an order, and every product needs at least one variant. Create your products and variants before you create carts and orders.

### Product retargeting emails

You can remind contacts about items they viewed in your store but did not purchase with product retargeting emails.

First, you'll need to [create a new store via the API](/marketing/api/ecommerce/create-store) or [connect a third-party store](https://mailchimp.com/help/connect-your-online-store-to-mailchimp/) to your Mailchimp account. Once your store is connected, embed JavaScript in your store pages that will relay information to Mailchimp about what products have been viewed. Most store platforms ask you to place this script in a header or footer element so it appears on every page on your store.

> **Note**
>
> **Note**: Not all stores support product retargeting emails. You can check this via the [`/ecommerce/stores/{store_id}`](/marketing/api/ecommerce/get-store) endpoint under `automations.abandoned_browse.is_supported`.

Depending on the requirements of your store platform, you may need to embed the JavaScript directly in your page or link to an external script hosted by Mailchimp. Both of these are accessible via the [`/ecommerce/stores/{store_id}`](/marketing/api/ecommerce/get-store) endpoint: `connected_site.site_script.fragment` contains the code, and `connected_site.site_script.url` contains the external script location.

You can verify that you have properly installed the script for your store by using the [`/connected-sites/{connected_site_id}/actions/verify-script-installation`](/marketing/api/connected-sites/create-action-verify-script-installation) endpoint, replacing `{connected_site_id}` with the unique `site_foreign_id` of your store. A successful verification will return an empty result, and an unsuccessful verification will return an error.

The product retargeting email workflow is configured as an automation, which you can [modify](https://mailchimp.com/help/create-a-product-retargeting-email/#Review_your_settings) alongside the [design of your retargeting email](https://mailchimp.com/help/create-a-product-retargeting-email/#Design_email), in the Mailchimp app.

## Carts

A cart is a customer's shopping cart saved before a successful purchase, and its [cart lines](/marketing/api/ecommerce/list-store-cart-lines) record which product variants the customer added.

### Abandoned cart emails

You can [create an abandoned cart email](https://mailchimp.com/help/create-an-abandoned-cart-email/) for any cart with a valid customer `email_address` and `checkout_url`. The email will be populated with information from the product variants contained in the cart lines within the abandoned cart. After the time specified in the abandoned cart notification settings, the email will be sent. If you remove the cart with a DELETE request before the time elapses, the corresponding abandoned cart email will be canceled. Carts do not automatically expire and will remain on Mailchimp's systems until deleted.

> **Note**
>
> **Note**: Cart data cannot be converted directly into an order—carts only exist for the purpose of triggering abandoned cart automations. However, it is possible to read the contents of a cart, create an order with those contents, and then delete the cart.

## Orders

An order is a successful transaction. When adding orders, the `processed_at_foreign` parameter is not required. However, if the orders are missing a date and timestamp, they will not show up on a contact's Activity Feed in the application.

To support [tracking campaign revenue](https://mailchimp.com/help/view-revenue-from-email-campaigns/), orders must include `campaign_id`, `processed_at_foreign` time, and `financial_status`.

> **Note**
>
> **Note**: Bringing over historical purchase data and customers depends on how your platform stores data. This data will help target customers and make product recommendations more accurate. We recommend bringing over at least six months of purchase/subscriber data, which should be done by [making calls through the batch endpoint](/marketing/api-concepts/batch-operations).

## Order notifications

[Order notifications](https://mailchimp.com/help/create-order-notifications/) are triggered by a change in a contact’s order status. After designing and enabling order notifications in your Mailchimp account, you can trigger those emails by [adding](/marketing/api/ecommerce/create-store-order) or [updating](/marketing/api/ecommerce/update-store-order) an e-commerce order with `financial_status` or `fulfillment_status` values.

An order’s `financial_status` can be `paid`, `pending`, `refunded`, or `cancelled`. Changing the status will trigger the following notifications:

| Notification | Description                                                                         |
| ------------ | ----------------------------------------------------------------------------------- |
| `paid`       | order invoice, notifying the customer that their order is paid in full              |
| `pending`    | order confirmation, notifying a customer if their order is unpaid or partially paid |
| `refunded`   | refund confirmation, notifying a customer that their refund has been processed      |
| `cancelled`  | cancellation confirmation, notifying a customer that their order has been cancelled |

Setting an order’s `fulfillment_status` to `shipped` will trigger a shipping confirmation, notifying a customer that their order has been shipped.

## Tracking and reports

You can add tracking parameters to e-commerce orders to track purchases that result from a campaign or product recommendation, and to monitor how much you are selling with Mailchimp. Data from orders with a `campaign_id` parameter will also appear in the Campaign Report.

When you send a campaign with e-commerce tracking enabled, any links in that campaign’s emails will contain additional tracking parameters that can be used with the e-commerce API.

### Email ID tracking parameter

The `mc_eid` parameter is a unique Mailchimp ID that identifies the recipient’s email address, which you can use to associate orders with a contact.

To find a contact’s email address, make an API call to the [Members](/marketing/api/lists/list-members) endpoint with the `mc_eid` as the value for the `unique_email_id` parameter. For example, if your subscriber’s link contains the tracking parameter `mc_eid=18d3c1adfe`, you can find that customer’s email address by making a GET request to `/lists/{list_id}/members?unique_email_id=18d3c1adfe`.

> **Note**
>
> **Note**: The `mc_eid` value is distinct from the MD5 hash of the lowercase email address, which is used by some other Marketing API endpoints.

### Campaign ID tracking parameter

The `mc_cid` parameter is the Mailchimp ID for the campaign that generated the link. You can [add e-commerce orders](/marketing/api/ecommerce/create-store-order) with the `mc_cid` as the value for the `campaign_id` parameter to indicate that the order resulted from a specific campaign.

## Product recommendations

Mailchimp's personalized [product recommendations feature](https://mailchimp.com/help/about-product-recommendations/) uses individual contact purchase data to prioritize and promote relevant items from a store. To enable product recommendations for the orders and products you add to Mailchimp, the following parameters are required:

* [Products](/marketing/api/ecommerce/list-store-products) require a valid `image_url` so your customers can see images of recommended products.
* [Product variants](/marketing/api/ecommerce/list-store-product-variants) require the `inventory_quantity` parameter. Product variants will only be recommended if this value is greater than 0, so items that are not available for purchase will not be recommended.
* [Orders](/marketing/api/ecommerce/list-store-orders) require a `processed_at_foreign` timestamp. This ensures that product recommendations are based on up-to-date e-commerce activity.

> **Note**
>
> **Note**: You can also track any purchases that result from a product recommendation. When a customer clicks on a recommended product, that link will include an `mc_tc` parameter in the URL. To track revenue resulting from product recommendations, use the value of `mc_tc` for the `tracking_code` parameter when adding an order.

## Pausing store automations

When you create or update a store in Mailchimp with the `is_syncing` parameter set to `true`, you will temporarily disable the following automations from triggering on any e-commerce data for that store:

* Order notifications
* Abandoned carts
* First purchases
* Specific-product follow-ups
* Any-product follow-ups
* Category follow-ups
* Best customers

While in this state, you can add, edit, or backfill e-commerce information without triggering messages from these campaigns. To resume these campaigns, [update the store](/marketing/api/ecommerce/update-store) and set `is_syncing` to `false`.

> Find all the Mailchimp API documentation and tools developers need to send marketing and transactional emails.