Get Started with the E-Commerce API 3.0

Mailchimp’s API 3.0 includes powerful e-commerce endpoints and data models. This guide explains how the Mailchimp e-commerce features tie to endpoints and helps developers build a platform that will sell more stuff.

Before You Start

  • Review Mailchimp’s basic API calls to make sure you are comfortable making those calls.
  • We encourage you to register in our Integrations Directory by applying to our Partner Program. Make sure that you use a custom user-agent string so that your integration shows up on in our logs.
  • We recommend Oauth2 for authentication.
  • To learn more about how Mailchimp’s e-commerce features can grow your business, refer to Sell More Stuff with Mailchimp.

Register Your Application

When you are ready to begin, register your application with Mailchimp following these steps:

  1. In your Mailchimp account, navigate to the Account page.
  2. In the drop-down menu, select Extras, and then API Keys.
  3. Under the “Developing an App?” heading, select Register, and then Manage Your Apps.
  4. Click Register an App.
  5. In the fields provided, enter your application’s information and click Create.

When creation is successful, a form displays with information at the end, including the Client_ID and Client Secret.

Do not share the Client_ID and Client Secret.

On this screen, you don’t need to save or change the information. Click Update or Cancel to go back to the Registered Apps page, or close the window.

E-Commerce Endpoints

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/audience, but a single list/audience can support multiple Stores. After a Store is created and tied to an list/audience, it cannot be connected to a different list/audience.

Here are a few of the endpoints used to create a Store and see information about the Stores connected to your Mailchimp account:

POST /ecommerce/stores A call to this endpoint connects a new Store to a Mailchimp list/audience.

GET /ecommerce/stores Use this endpoint to view information about all stores.

GET /ecommerce/stores/store_id This endpoint provides information about a specific store.

Example

Example JSON Body of connecting a new Store using the POST /ecommerce/stores endpoint:

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

Customers

A Customer must be associated with a contact in a Mailchimp list/audience. It’s important to be aware of the relationship between e-commerce customers and contacts.

POST /ecommerce/stores/{store_id}/customers This endpoint adds a new customer to a store.

If your current e-commerce set up assigns a 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. If a customer’s email address is not already in a list/audience, they will be added with the subscription status determined by the opt_in_status parameter passed for that customer.

Note

Customers who do not opt in to your Mailchimp list/audience will be added as Transactional members. Although the opt in status parameter is there, it will not overwrite the status of a pre-existing contact. False = transactional; True = subscribed

Carts

Use these endpoints to temporarily save a customer’s shopping cart data pending a successful purchase, or to create an abandoned cart automation.

POST /ecommerce/stores/store_id/carts Use this endpoint to add a new cart to a store.

GET /ecommerce/stores/store_id/carts Use this endpoint to get information about a store’s carts.

Note

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

Abandoned cart automation is triggered by carts call. To remove a customer from a workflow, send delete call/delete cart.

Orders

An Order represents a successful purchase. This data can be used to provide more detailed campaign reports, track sales, personalize emails to targeted lists/audiences, and view other e-commerce data in your Mailchimp accounts.

POST /ecommerce/stores/{store_id}/orders

This endpoint adds a new order to a store.

See order lines.

Example response:

{
  "id": "ord0001",
  "customer": {
    "id": "cust0005",
    "email_address": "freddy@freddiesjokes.com",
    "opt_in_status": true,
    "company": "Mailchimp",
    "first_name": "Freddy",
    "last_name": "Von Chimpenheimer",
    "orders_count": 1,
    "total_spent": 10.25,
    "address": {
      "address1": "",
      "address2": "",
      "city": "",
      "province": "",
      "province_code": "",
      "postal_code": "",
      "country": "",
      "country_code": ""
    }
  }
}

Note

Bringing over historical purchase data and customers depends on how the platform itself stores data and can be done via batch operations. We recommend bringing at least 6 months of purchase/subscriber data over. This data will help target customers and product recommendation suggestions will be more accurate.

After your data is 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.

Order Notifications

Order notifications are triggered by a change in a contact’s order status. Send receipts and invoices, and update your customers on shipping, refunds, and cancellations using the API 3.0.

After you have 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 are not 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 are not 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.

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 must be added to a store before it can be added to a cart or an order. To add new products to a store, use these endpoints.

POST /ecommerce/stores/store_id/products

Add a new product to a store.

POST /ecommerce/stores/store_id/products/product_id/variants

Use this endpoint to add a new variant to the product. One variant is required for each product.

POST /ecommerce/stores/store_id/products/product_id/images

This endpoint will add a new image to a specific product.

Note

To segment a campaign by “Category Purchased,” products should have a value defined for the “Vendor” parameter for our API to recognize it.

Product Recommendations

This feature uses a customer’s historical purchase data to prioritize and promote a store’s relevant products

Include the following parameters to enable Product Recommendations for any Orders and Products that you add to Mailchimp:

  • Products require a valid image_url so your customers can 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 do not want to recommend a specific item unless it is 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.

Promo Codes

The promo code feature allows users to drag a promo block into their campaign that pulls from existing discount codes from the connected store. Use these endpoints to apply promo codes to a store.

POST /ecommerce/stores/store_id/promo-rules

This endpoint adds a new promo rule to a store.

POST /ecommerce/stores/store_id/promo-rules/promo_rule_id/promo-codes

This endpoint adds a new promo code to a store.

Promo Rules help you create promo codes for your campaigns. Promo Rules define generic information about promo codes like expiration time, start time, amount of discount being offered etc.

Promo Codes can be created for a given promo rule. All promo codes under a promo rule share the generic information defined by that rule like the amount, type, expiration date etc.

Connected Sites (mc.js)

Users can quickly review their list/audience settings, create abandoned cart emails, auto enable pop-up forms, retargeting emails, all by using mc.js. To manage the sites connected to Mailchimp with mc.js, use these endpoints.

GET /connected-sites A call to this endpoint returns a list of all connected sites for the current account.

GET /connected-sites/connected_site_id A call to this endpoint returns details on a connected site.

POST /connected-sites/connected_site_id/actions/verify-script-installation A call to this endpoint confirms that the script loader has been added into the specified connected site.

Learn more about the connected sites parameters.

E-commerce Tracking and Reports

Add tracking parameters to your e-commerce orders to track purchases that result from a Mailchimp campaign, or product recommendation, and monitor how much stuff you are selling with Mailchimp. Data from orders with a campaign_id are also visible in any 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.

  • 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 subscribed contact. You can make an API call to the /lists/{list_id}/members endpoint 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 request to the GET /lists/list_id/members?unique_email_id=18d3c1adfe endpoint.

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.

Note

You can also track any purchases that result from a Mailchimp Product Recommendation. 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.

Double Opt-In

Mailchimp offers two opt-in settings for our audiences. Double opt-in includes an extra confirmation step that verifies each email address. In order for double opt-in emails to be sent properly, you will need to make a POST request to the customers endpoint followed by a PATCH request to the list/{list_id}/members/{subscriber_hash} endpoint.

In the body of the POST request to the customers endpoint, you will need to send a value of false for the opt_in_status field. This will add the customer as a transactional member. Sending a value of true would add them as a subscriber and opt them into marketing emails. The next step is to make a call to edit the list member with a status value of pending. This can be done via a PATCH request to the lists/{list_id}/members/{subscriber_hash} endpoint. Learn more about editing list members here.

Syncing an E-Commerce Store

When you create or update a store in Mailchimp with the is_syncing parameter set to true, you will temporarily disable these automations from triggering off of any e-commerce data for that store. Now you can add, edit, or backfill e-commerce information without sending any of these campaigns:

  • Abandoned carts
  • First purchases
  • Specific product follow-ups
  • Any product follow-ups
  • Category follow-ups
  • Best customers