Mailchimp Developer LogoMailchimp Developer Wordmark

E-Commerce

The basics

The E-commerce endpoints allow you to connect an external store to your Mailchimp account. In turn, this allows you to access Mailchimp’s e-commerce features, including order notifications, abandoned cart automations, follow-ups, product recommendations, and more.

Stores

Stores is the top-level e-commerce endpoint. Carts, customers, orders, and products all exist inside of the scope of a store. Some Stores parameters are always required, while others are only required in certain cases—for example, the domain parameter is necessary to enable Connected Sites and Google Ads. 

When creating a new store, the required store ID is client-defined. Each store must be tied to a Mailchimp audience (which uses the Lists/Audiences endpoint), but a single audience can support multiple stores. After a store is created and tied to an audience, it cannot be connected to a different audience.

Note: Mailchimp Stores 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. 

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: 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 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 represents an item for sale in a store. Each product exists as its own parent entity that must contain one or more product variants, and a product must be added to a store before it can be added to a cart or an order. You must create products before you can 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 or connect a third-party store 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: Not all stores support product retargeting emails. You can check this via the /ecommerce/stores/{store_id} 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} 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 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 alongside the design of your retargeting email, in the Mailchimp app.

Carts

The Carts endpoint lets you temporarily save a customer’s shopping cart prior to a successful purchase. Carts contain cart lines, which represent information about products that customers have added to their shopping carts.

Abandoned cart emails

You can 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: 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

The Orders endpoint represents successful transactions. 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, orders must include campaign_id, processed_at_foreign time, and financial_status.

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.

Order notifications

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 or updating 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:

NotificationDescription

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 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: 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 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 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 require a valid image_url so your customers can see images of recommended products.

  • 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 require a processed_at_foreign timestamp. This ensures that product recommendations are based on up-to-date e-commerce activity.

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 and set is_syncing to false.