Get Started with the E-Commerce API

MailChimp’s e-commerce API 3.0 endpoints allow you to add data from purchases to MailChimp and to associate this data with your list members and campaigns. These endpoints create a flexible, powerful tool that you can use to connect your current e-commerce platform with MailChimp to learn more about your customers.

Before You Start

If you’re new to the MailChimp API, we recommend our guide, Get Started with the MailChimp API, for more information about how to interact with API resources.

To learn more about how MailChimp’s e-commerce features can grow your online business, check out our How to Use MailChimp for E-Commerce Knowledge Base article.

In this guide, you’ll learn about the e-commerce resources you can use to track your store’s carts, orders, products, and customers.

Resources

MailChimp’s e-commerce endpoints use a Store as the top-level resource. In each Store, you’ll use Carts, Customers, Orders, and Products as the main resources. Cart Lines, Order Lines, and Product Variants exist as sub-resources of Carts, Orders, and Products.

Stores

A Store is the top-level e-commerce resource. Carts, Customers, Orders, and Products all exist inside of the scope of a Store. Each Store must be tied to a specific MailChimp list, but a single list can support multiple Stores. After a Store is created and tied to its list, it cannot be connected to a different list.

To connect a new Store to a MailChimp list, for example, you could POST this JSON body to https://usX.api.mailchimp.com/3.0/ecommerce/stores:

{
  "id" : "store_001",
  "list_id" : "205d96e6b4",
  "name" : "Freddie's Jokes",
  "domain" : "www.freddiesjokes.com",
  "email_address" : "merchandise@freddiesjokes.com",
  "currency_code" : "USD"
}

Carts

A Cart represents an unfinished transaction and includes the items a customer has added to their shopping cart, but not yet purchased. Use Carts to temporarily save a customer’s shopping cart data pending a successful purchase, or to represent an abandoned cart. See About Carts and Orders for information about converting a Cart to an Order.

Cart Lines

A Cart Line represents a single line item, or Product Variant, in a Cart. Each Cart Line represents an item in a customer’s shopping cart. For example, a Cart with two distinct items would contain two separate Cart Lines.

Here’s an example:

{
  "id" : "cart_001",
  "customer" : {
    "id" : "customer_001"
  },
  "campaign_id" : "b03bfc273a",
  "checkout_url" : "freddiesjokes.com/cart/?checkout=xxxx",
  "currency_code" : "USD",
  "order_total" : 25,
  "lines" : [
    {
      "id" : "line_001",
      "product_id" : "product_q_123",
      "product_title" : "Freddie Shirt",
      "product_variant_id" : "product_q_123_medium",
      "product_variant_title" : "Medium Shirt",
      "quantity" : 1,
      "price" : 15
    },
    {
      "id" : "line_002",
      "product_id" : "product_z_123",
      "product_title" : "Freddie Figurine",
      "product_variant_id" : "product_z_123",
      "product_variant_title" : "Freddie Figurine",
      "quantity" : 1,
      "price" : 10
    }
  ]
}

Customers

A Customer represents an e-commerce customer that’s tied to a member in a MailChimp list. This relationship can result in changes to your MailChimp list members’ subscription status when you add or update Customers.

If a customer makes a purchase on your online store and opts in to receive your newsletters as part of the registration process, for example, you can add that e-commerce Customer and subscribe them to the connected list in a single API call:

{
  "id" : "customer_001",
  "email_address" : "freddie@freddiesjokes.com",
  "first_name" : "Freddie",
  "last_name" : "Von Chimpenheimer",
  "opt_in_status" : true
}

Orders

An Order represents a successful transaction. Orders can track valuable e-commerce data, including which email campaign generated the order or whether the order resulted from a Product Recommendation.

Order Lines

An Order Line represents a specific item, or Product Variant, purchased as part of an Order.

The following Order consists of three total items, but only two Order Lines because there are two distinct Product Variants. One Variant has a quantity of 2.

{
  "id" : "order_001",
  "customer" : {
    "id" : "customer_001"
  },
  "campaign_id" : "b03bfc273a",
  "checkout_url" : "freddiesjokes.com/cart/?checkout=xxxx",
  "currency_code" : "USD",
  "order_total" : 40,
  "shipping_address" : {
    "address1" : "675 Ponce de Leon Ave NE",
    "address2" : "Suite 5000",
    "city" : "Atlanta",
    "province" : "GA",
    "province_code" : "30033"
  },
  "lines": [
     {
      "id" : "order_001",
      "product_id" : "product_q_123",
      "product_title" : "Freddie Shirt",
      "product_variant_id" : "product_q_123_medium",
      "product_variant_title" : "Medium Shirt",
      "quantity" : 2,
      "price" : 30
    },
    {
      "id" : "order_002",
      "product_id" : "product_z_123",
      "product_title" : "Freddie Figurine",
      "product_variant_id" : "product_z_123",
      "product_variant_title" : "Freddie Figurine",
      "quantity" : 1,
      "price" : 10
    }
  ]
}

Products

A Product represents an item for sale in a Store. Each Product exists as a parent entity that must contain one or more Product Variants, and must be added to a Store before it can be added to a Cart or an Order.

Product Variants

A Product must have one or more Variants. Product Variants can be used for items that may come in slightly different versions, like shirt sizes:

{
  "id" : "product_q_123",
  "title" : "Freddie Shirt",
  "variants" : [
    {
      "id" : "product_q_123_small",
      "title" : "Small Shirt",
      "price" : 15
    },
    {
      "id" : "product_q_123_medium",
      "title" : "Medium Shirt",
      "price" : 15
    },
    {
      "id" : "product_q_123_large",
      "title" : "Large Shirt",
      "price" : 15
    }
  ]
}

If your system doesn’t support the concept of variants, you can adapt any products to our e-commerce resource model by creating a Product with a single Product Variant:

{
  "id" : "product_z_123",
  "title" : "Freddie Figurine",
  "variants" : [
    {
      "id" : "product_z_123",
      "title" : "Freddie Figurine",
      "price" : 10
    }
  ]
}

Note

You don’t have to match the top-level Product id with the Product Variant id, but it can make it easier to implement single-variant Products in MailChimp’s e-commerce system.

Using the API

Our e-commerce API is a powerful tool that you can use to integrate your existing e-commerce platforms or systems with MailChimp. To provide more flexibility, the e-commerce API lets you define a custom id for each resource, with a limit of 50 characters.

This design allows more flexible integration with any existing e-commerce platforms or systems. Instead of having to update existing customers in your system with a new foreign id that’s automatically generated by MailChimp, you can reuse any existing ids and naming conventions. When you add a resource to MailChimp, you don’t have to to wait for an API response to get the resource’s id.

Using Custom IDs

If your current e-commerce system assigns each customer an ID such as customer_01, customer_02, customer_03, etc. you can add those customers to MailChimp without requiring a new ID string.

You could perform a GET request to /ecommerce/stores/this_store_0001/customers/customer_01 to check whether that user has already been added, for example, and make a POST request to add them with the existing customer id in your system.

Alternatively, use a PUT request instead of separate GET and POST requests. This would update an existing Customer with the data passed in the PUT request, or create a new Customer if that id doesn’t already exist in MailChimp.

About Subscribers and Customers

A Customer must be associated with a subscriber in a MailChimp list, so it’s important to be aware of the relationship between e-commerce Customers and list members.

Using the e-commerce API to add or update a Customer can work differently depending on whether that Customer’s email address is already present on the Store’s connected list.

  • If the customer’s email address is already on the list, no changes to that list member’s subscription status will take place. The opt_in_status flag passed via the e-commerce API will never overwrite the subscriber status of an existing list member.
  • If the customer’s email address is not on the list, they’ll be added to the list with the subscription status determined by the opt_in_status parameter passed for that Customer.
    • Customers added with opt_in_status set to ”true” will be added to the connected List with the status “subscribed”
    • Customers added with opt_in_status set to ”false” will be added to the connected List with the status “transactional”

You can only change an existing Customer’s list subscription status via the e-commerce API endpoints when that customer’s subscription status is “transactional.”

About Carts and Orders

Carts and Orders include much of the same information, but there’s no relationship between these resources. A Cart represents an unfinished transaction, while an Order represents a successful purchase.

Carts will continue to exist on our systems until deleted, and Cart data cannot be converted directly into an Order.

For example, if you store a Customer’s abandoned cart data as a Cart, and the customer later resumes shopping and purchases those items, you would need to create a new Order. Then, you can delete the Cart to reflect the customer’s successful transaction.

About Product Recommendations

MailChimp can offer personalized Product Recommendations to your customers based on their individual purchase data. This powerful feature can help increase e-commerce revenue and engage your customers, and is available to users who add e-commerce data to MailChimp using API 3.0.

To enable Product Recommendations, any Orders and Products that you add to MailChimp need to include the following parameters:

  • Products require a valid image_url so your customers will be able to see images of any recommended products.
  • Product Variants require the inventory_quantity parameter. Product Variants will only be recommended if this value is >0, since we don’t want to recommend a specific item unless it’s available for purchase.
  • Orders require a processed_at_foreign time stamp. This data ensures that your customers’ Product Recommendations based are on up-to-date e-commerce activity.

About E-Commerce Tracking

Add tracking parameters to your e-commerce orders using API 3.0 to track purchases that result from a MailChimp campaign or Product Recommendation and monitor how your marketing campaigns increase revenue.

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:

  • mc_eid is a unique MailChimp ID that identifies the recipient’s email address.
  • mc_cid is the MailChimp ID for the campaign that generated the link.

Use the mc_eid value from the tracking URL to associate orders with a list member. You can make an API call to /lists/{list_id}/members and filter the results by the unique_email_id value from the mc_eid in the link to find the email address for that recipient, which you can then use to identify the customer for your order. For example, if your subscriber’s link contains the mc_eid=18d3c1adfe tracking parameter, you can find that customer’s email address by making a GET request to https://usX.api.mailchimp.com/3.0/lists/{list_id}/members?unique_email_id=18d3c1adfe.

E-commerce Orders can be added with the mc_cid ID as the value for the campaign_id parameter to indicate that the order resulted from a specific campaign. E-commerce data from orders with a campaign_id will also be visible in any Campaign Reports.

You can also track any purchases that result from a Product Recommendations provided by MailChimp. When one of your customers clicks on a recommended product, that link will include mc_tc=prec in the URL. Use this value for the tracking_code parameter when adding an order to track revenue resulting from product recommendations.

Syncing an E-Commerce Store

E-commerce data can be especially powerful when used in combination with MailChimp’s automations. For example, you could configure a follow-up email to a customer whenever they leave unpurchased items in their cart. Sometimes, however, you may not want changes or additions to your e-commerce data to trigger new automations, such as when you’re backfilling existing purchase data to MailChimp.

Creating or updating a store in MailChimp with the is_syncing parameter set to true will temporarily disable the following automations from triggering off of any e-commerce data for that store, allowing you to add, edit, or backfill e-commerce information without sending any unwanted emails:

  • Abandoned cart email
  • First purchase
  • Specific product follow-up
  • Any product follow-up
  • Category follow-up
  • Best customers

Once your data has been synced, make a PATCH call to the e-commerce store with "is_syncing": "false" to allow that store’s e-commerce data to trigger automations as normal.

Orders_count and Total_spent

You can create and update e-commerce Customers with two (optional) parameters: orders_count and total_spent. Adding this data to MailChimp can help you identify and segment customers based on their shopping and spending habits.

These values do not update automatically in MailChimp when you create or update an order using the Orders API endpoint. Instead, you can update these parameters’ values by making a PATCH or PUT call to /ecommerce/stores/{store_id}/customers/{customer_id}.

Order Notifications

Adding e-commerce orders using API 3.0 allows you to automatically trigger order notification emails to your customers. Once you’ve designed and enabled order notifications in your MailChimp account, you can trigger those emails by adding or updating an e-commerce order with specific financial_status or fulfillment_status values.

Notification Types and Triggers

Parameter/Value Notification type Description
"financial_status": "paid" Order Invoice Notifies customers that their payment has been processed. This is only recommended if customers aren’t charged at time of order. If customers are charged at time of order, use the Order Confirmation instead.
"financial_status": "pending" Order Confirmation Sends a receipt to customers when they buy something from your store. If customers aren’t charged at time of order, use the Order Invoice instead.
"financial_status": "refunded" Refund Confirmation Notifies customers that their refund has been processed.
"financial_status": "cancelled" Cancellation Confirmation Notifies customers that their order has been cancelled.
"fulfillment_status": "shipped" Shipping Confirmation Notifies customers that their order is on the way.

API 3.0 vs. Older Versions

MailChimp’s API 3.0 involves a complete redesign of the way we treat e-commerce and customer data, allowing you to store more data and better integrate this data with your list subscribers. E-commerce data in 3.0 isn’t compatible with any e-commerce data added via older versions of the API.

Using API 3.0 provides access to several advanced features that weren’t possible using previous versions of the API:

The e-commerce endpoints in API 3.0 provide complete feature parity with the older e-commerce data, but with more flexibility in how you manage this data. For example, the resource structure in 3.0 lets you add and update product information at any time, allowing for more accurate syncing between your store and MailChimp. With older versions of the API, product data could only be managed as part of a new order.

You can also use API 3.0 to add e-commerce data for customers that haven’t subscribed to your MailChimp list. You can create an order for your customer without checking that the customer exists as a list member, and this purchase data will be visible in MailChimp’s reports even if that customer doesn’t opt into your MailChimp list.

Note

After you add e-commerce data to a list with API 3.0, any reports or segments that were based on e-commerce data added via older versions of the API will no longer be accessible. This older e-commerce data isn’t deleted, and you can access the data using older API versions.