Get Started with the E-Commerce API

Mailchimp’s API 3.0 includes powerful e-commerce endpoints and data models. This guide will serve as a quick resource that ties our e-commerce features to the necessary endpoints and help developers build a platform that will sell more stuff.

Before You Start

  • Review Mailchimp’s basic API calls to make sure you’re comfortable making those calls.
  • We encourage you to register in our Integrations Directory by applying to our Partner Program. Use a custom user-agent string so we can see your integration in our logs.
  • We recommend Oauth2 for authentication.
  • To learn more about how Mailchimp’s e-commerce features can grow your business, check out our Knowledge Base article: Sell More Stuff with Mailchimp.

Register Your Application

When you’re ready to begin, register your application with Mailchimp:

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

When creation is successful, you’ll see a form appear 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, 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.

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.

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. It’s important to be aware of the relationship between e-commerce Customers and list members.

POST /ecommerce/stores/{store_id}/customers This endpoint will add 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 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.

Note

Customers who don’t opt in to your Mailchimp list will be added as Transactional members. Although the optin 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 audiences, and view other e-commerce data in your Mailchimp accounts.

POST /ecommerce/stores/{store_id}/orders

This endpoint will add 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 will depend 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.

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.

Order Notifications

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

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.

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

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 will add a new promo rule to a store.

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

This endpoint will add 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 settings, create abandoned cart emails, auto enable pop-up forms, retargeting emails, all by using mc.js. To manage the sites you’ve connected to Mailchimp with mc.js, use these endpoints.

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

GET /connected-sites/connected_site_id A call to this endpoint will return details on the specified connected site.

POST /connected-sites/connected_site_id/actions/verify-script-installation A call to this endpoint will confirm 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’re selling with Mailchimp. Data from orders with a campaign_id will also be visible in any Campaign Reports.

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

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