Skip to main content

Mailchimp

Mailchimp is a marketing automation platform that helps you build email campaigns, manage audience segments, and track customer behavior. Use this integration to automatically sync customer profiles from your CommerceBuild store to a Mailchimp audience and send purchase events that trigger automations or power segmentation.

How to set it up​

Where to find it: Admin → Notification → Mailchimp

When you'd use this: When you want customer email addresses and profile data to automatically appear in your Mailchimp audience so you can send marketing campaigns and track customer purchase activity.

What you need first:

  • A Mailchimp account with an active audience (list)
  • Your Mailchimp API key (must include the data center code, e.g., yourkey-us1)
  • Your Mailchimp audience/list ID (found in Mailchimp under Audience → Settings → Audience name and defaults)

Set it up:

  1. Navigate to Admin → Notification → Mailchimp
  2. Enable the integration
  3. Enter your Mailchimp API key in the apiKey field
  4. Enter your audience/list ID in the listId field
  5. Enter your data center code (e.g., us1, us19) in the dc field
  6. Save the configuration

The data center (dc) parameter corresponds to the portion of your API key after the hyphen. For example, if your API key is abc123-us19, your data center is us19.

Configuration options​

FieldWhat it doesDefaultRequired
apiKeyYour Mailchimp API key, used to authenticate requests to the Mailchimp APINoneYes
listIdThe unique identifier for the Mailchimp audience (list) where customer data will be syncedNoneYes
dcThe data center code for your Mailchimp account (e.g., us1, us19), which determines the API endpoint URLNoneYes

Using it day-to-day​

  1. Customer profile sync happens automatically — When a customer is created or updated in your store, their information syncs to Mailchimp. The system uses the customer's email address (converted to an MD5 hash) to identify the subscriber. New customers are added with a status of subscribed, and existing members are updated with the latest information.

  2. Customer data includes contact details and address — The following fields sync to Mailchimp merge fields: first name (FNAME), last name (LNAME), phone number (PHONE), and full address (street address lines 1 and 2, city, state, zip, and country).

  3. Bulk sync is available for batch operations — Use the bulkAddOrUpdateMembers operation to add or update up to 500 members at once. The operation returns totals for created records, updated records, and errors.

  4. Purchase events track customer behavior — The integration automatically sends custom events to Mailchimp when customers interact with your store:

    • started_checkout — Sent when a customer begins the checkout process
    • placed_order — Sent when a customer completes an order
    • ordered_product — Sent for each item in an order

  5. Events appear in Mailchimp member profiles — These events can be used to build segments (e.g., "customers who placed an order in the last 30 days") or trigger automations (e.g., send a follow-up email after checkout is started but not completed).

Troubleshooting​

  • Customer not appearing in Mailchimp — Verify the customer record has a valid email address. The sync uses the email address as the primary identifier and cannot sync customers without one.

  • 401 Unauthorized or authentication errors — Check that your API key is correct and includes the data center suffix (e.g., yourkey-us1). Ensure the API key has not been revoked in your Mailchimp account settings.

  • 404 Not Found when syncing — Verify that the listId matches an active audience in your Mailchimp account and that the dc field matches the data center portion of your API key. A mismatch will cause requests to be routed to the wrong Mailchimp server.

  • Event not appearing for a customer — Events require the customer's email address to generate the subscriber hash. If the email is missing or has changed since the customer was added to Mailchimp, the event may fail to associate with the correct member.

  • Bulk operation reports errors — Check the errorCount field in the response. The Mailchimp API may reject individual members due to invalid email formats, missing required merge fields, or duplicate entries. Review the error details returned by Mailchimp to identify which records failed.