E-Commerce

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 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.

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.

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.

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.

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.

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.

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.

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:

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

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.

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.

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.

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.