> For the complete documentation index, see [llms.txt](https://help.dollarlabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.dollarlabs.io/dollarback-store-credit/integrations/mailchimp-integration.md).

# Mailchimp integration

Connect Mailchimp to send every DollarBack credit event to your customers' Mailchimp contacts and keep each contact's credit balance and referral code in merge fields, so you can build Customer Journeys, segments, and campaigns around store credit.

## Prerequisites

* A Mailchimp account with access to the audience your customers are in.
* Your Shopify customers must already be **contacts in that audience**, with the same email address as in Shopify. DollarBack updates existing contacts only; it never adds new contacts to your audience. If your customers aren't in Mailchimp yet, export them from **Shopify admin → Customers → Export** and import the file as contacts in Mailchimp.
* A DollarBack plan that includes integrations. On other plans, the Mailchimp page shows **Upgrade to Connect**.
* At least one active earning program, so there are events to sync ([Set up purchase cashback](https://help.dollarlabs.io/dollarback-store-credit/earning-cashback-programs/set-up-purchase-cashback.md)).

## Connect Mailchimp

1. Go to **DollarBack admin → Integrations** and find the **Mailchimp** card. Click **Set up**.
2. Click **Connect with Mailchimp**. A Mailchimp window opens.
3. Log in to the Mailchimp account you want linked, then click **Allow** on the **Authorize Dollarback** screen. The window shows "Connected to Mailchimp" and closes by itself.
4. Back on the Mailchimp page, the badge shows **Connected**. If it still shows **Not Connected**, reload the page.
5. Under **Audience**, select the audience your Shopify customers are synced into, and click **Save**. DollarBack adds its merge fields to that audience. Nothing is sent until an audience is saved.

<figure><img src="https://2844543096-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcVBfwy7Yj4tU8TsxkHEr%2Fuploads%2Fgit-blob-50e0f24dbb461ef57c568d0415b6322570818ee6%2Fdb-mailchimp-hub-card.png?alt=media" alt="The Integrations page in DollarBack. The Marketing and automations section shows cards for Klaviyo, Omnisend, Mailchimp, Shopify Flow and Judge.me. The Mailchimp card shows Not Connected and a Set up button."><figcaption><p>Start on the Integrations page and click Set up on the Mailchimp card.</p></figcaption></figure>

<figure><img src="https://2844543096-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcVBfwy7Yj4tU8TsxkHEr%2Fuploads%2Fgit-blob-7a25a1122a6e39e64e54f270f47c28b5a512c948%2Fdb-mailchimp-connect.png?alt=media" alt="The Mailchimp integration page in DollarBack with a Not Connected badge and a Connect with Mailchimp button."><figcaption><p>Connect with Mailchimp opens the Mailchimp login in a new window.</p></figcaption></figure>

<figure><img src="https://2844543096-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcVBfwy7Yj4tU8TsxkHEr%2Fuploads%2Fgit-blob-91de4f5bab768365f07b2a1f7313d779afddb020%2Fdb-mailchimp-authorize.png?alt=media" alt="The Mailchimp Authorize Dollarback screen, showing Dollarback by Dollarlabs, tips about authorized apps, and the Allow and Cancel buttons."><figcaption><p>After you log in, Mailchimp asks you to allow DollarBack to access your account. Click Allow.</p></figcaption></figure>

<figure><img src="https://2844543096-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcVBfwy7Yj4tU8TsxkHEr%2Fuploads%2Fgit-blob-727b1bc1860fcca8377ff4cb73dc3bf8872aed9c%2Fdb-mailchimp-connected-audience.png?alt=media" alt="The Mailchimp integration page with a Connected badge, the buttons Disconnect Mailchimp, Sync Balance and Send Demo Events, and the Audience card with an audience selected."><figcaption><p>Once connected, choose the audience your customers are in and click Save.</p></figcaption></figure>

{% hint style="info" %}
If you have several audiences, pick the one your Shopify customers are synced into. A customer who is not a contact in the saved audience is skipped: DollarBack does not create the contact, and no event is recorded for them.
{% endhint %}

## Synced events

Each event is recorded on the contact in Mailchimp, matched by the customer's email address. Use these exact names when you build a Customer Journey or a segment on events:

| Mailchimp event                                                                                                     | Fires when                                                                                                                     | Key properties                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| store\_credit\_credited                                                                                             | Credit is issued (order cashback, signup, newsletter, review, Flow deposit, bulk import with the integrations toggle on, etc.) | amount, formattedAmount, currency, symbol, reason, expiresAt, formattedExpiresAt, expiryDays, orderId, orderName, offerTitle                        |
| store\_credit\_debited                                                                                              | Credit is removed (refund clawback, manual or bulk-import debit)                                                               | amount, formattedAmount, currency, symbol, reason, orderId, orderName                                                                               |
| store\_credit\_redeemed                                                                                             | A customer pays for an order with credit                                                                                       | amount, formattedAmount, currency, symbol, reason, orderId, orderName                                                                               |
| birthday\_reward                                                                                                    | A birthday reward is issued as store credit                                                                                    | amount, formattedAmount, currency, symbol, reason, expiresAt, formattedExpiresAt, expiryDays                                                        |
| store\_credit\_expiring                                                                                             | Credit crosses a reminder threshold in your Expiry Notification Schedule                                                       | amount, formattedAmount, currency, symbol, reason, expiresAt, formattedExpiresAt, remainingDays, transactionId                                      |
| referral\_code\_generated                                                                                           | A referral code is created for a customer                                                                                      | referralCode, reason                                                                                                                                |
| referral\_rewarded                                                                                                  | A referrer earns store credit                                                                                                  | amount, formattedAmount, currency, symbol, reason, expiresAt, formattedExpiresAt, expiryDays, orderId, orderName, refereeFirstName, refereeLastName |
| discount\_code\_credit                                                                                              | A reward discount code is issued, earned through a program or claimed in the marketplace                                       | discountCode, rewardSummary, offerTitle, reason, orderId, orderName, amount, formattedAmount                                                        |
| discount\_code\_expiring                                                                                            | An unused reward discount code crosses a reminder threshold                                                                    | discountCode, rewardSummary, offerTitle, reason, expiresAt, formattedExpiresAt, remainingDays                                                       |
| tier\_upgraded / tier\_downgraded                                                                                   | The customer moves to a higher or lower tier                                                                                   | tier, previousTier, reason                                                                                                                          |
| membership\_activated, membership\_renewed, membership\_payment\_failed, membership\_cancelled, membership\_expired | A paid membership starts, renews, fails a payment, is cancelled or ends                                                        | planName, tier, status, expiresAt, formattedExpiresAt, nextBillingAt, price, formattedPrice, endReason                                              |

Property values reach Mailchimp as text. Dates are in your store's time zone:

| Property           | Example                           |
| ------------------ | --------------------------------- |
| amount             | 25.5                              |
| formattedAmount    | ₹25.50                            |
| expiresAt          | December 31, 2026                 |
| formattedExpiresAt | December 31, 2026 at 11:59 PM EST |

`expiresAt` and `formattedExpiresAt` are sent only when the credit has an expiry date.

<figure><img src="https://2844543096-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcVBfwy7Yj4tU8TsxkHEr%2Fuploads%2Fgit-blob-54d9d32499f5a30ea22a61880d9f631cb99314ed%2Fdb-mailchimp-synced-events.png?alt=media" alt="The Synced Events panel on the Mailchimp integration page, listing store_credit_credited, store_credit_debited, store_credit_redeemed, birthday_reward and store_credit_expiring under Store credit, then the Referral and Discount codes events."><figcaption><p>The Mailchimp page lists every event DollarBack sends, grouped by program.</p></figcaption></figure>

{% hint style="info" %}
There is no event when credit actually expires. To reach customers at the last moment, add a 1-day threshold to your Expiry Notification Schedule and use *store\_credit\_expiring* where `remainingDays` is 1.
{% endhint %}

## Merge fields

When you save an audience, DollarBack adds these merge fields to it (hidden from signup forms). Every event updates them on the contact:

| Merge field tag | Name in Mailchimp  | Contains                                                    |
| --------------- | ------------------ | ----------------------------------------------------------- |
| `DBBALANCE`     | dbBalance          | The customer's current store-credit balance as a number     |
| `DBFBALANCE`    | dbFormattedBalance | The balance formatted for display (e.g. ₹30.25)             |
| `DBCURRENCY`    | dbCurrency         | The balance's currency code (e.g. INR)                      |
| `DBSYMBOL`      | dbSymbol           | The currency symbol (e.g. ₹)                                |
| `DBREFCODE`     | dbReferralCode     | The customer's referral code (set when a code is generated) |

In a campaign or journey email, write the tag between `*|` and `|*`, for example "You have `*|DBFBALANCE|*` in store credit."

{% hint style="info" %}
The note under the audience picker in DollarBack shows shortened names (DB\_BAL, DB\_CUR and so on). In Mailchimp, use the tags in the table above.
{% endhint %}

<figure><img src="https://2844543096-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcVBfwy7Yj4tU8TsxkHEr%2Fuploads%2Fgit-blob-8855fa8b0298e647c695fc63f3c3b60e541dff1e%2Fdb-mailchimp-synced-properties.png?alt=media" alt="The Synced Properties panel listing the merge tags DBBALANCE (Number), DBFBALANCE, DBCURRENCY, DBSYMBOL and DBREFCODE (String) with a description and example for each."><figcaption><p>The merge tags DollarBack keeps up to date on each contact.</p></figcaption></figure>

## Buttons on the Mailchimp page

| Button               | What it does                                                                                                                                                                                               |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sync Balance         | Sends every customer's current balance to the merge fields, for contacts that already exist in the audience                                                                                                |
| Send Demo Events     | Adds one test contact, <dummy@dollarlabs.io> (transactional, not subscribed to marketing), and sends every event to it with sample values, so you can build journeys before a real customer earns anything |
| Disconnect Mailchimp | Stops all sends at once                                                                                                                                                                                    |

## Journey and campaign ideas

* **Credit reminder journey**: start a Customer Journey on the *store\_credit\_credited* event, wait 7 days, and email contacts who haven't ordered since: "You still have `*|DBFBALANCE|*` waiting."
* **Expiry winback**: start on *store\_credit\_expiring* and send an urgency email that uses `remainingDays` and `formattedAmount`. Pairs with (or replaces) DollarBack's own expiry reminder email.
* **Balance segment**: a segment where *dbBalance* is greater than 0 for "has credit to spend" campaigns. Add `*|DBREFCODE|*` to newsletters to promote sharing.

{% hint style="warning" %}
If you rebuild an email in Mailchimp (for example the credited notification), consider disabling the matching DollarBack template under **Notifications** so customers don't receive both.
{% endhint %}

## Verify it works

1. Make sure a test customer is a contact in the saved audience, with the same email address as in Shopify.
2. Trigger a credit: place a small test order, or credit the customer with a bulk import that has **Send to Integrations** turned on.
3. In Mailchimp, open that contact: the *store\_credit\_credited* event should appear in the contact's activity within a few minutes, and the *dbBalance* merge field should match the widget balance.

<figure><img src="https://2844543096-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcVBfwy7Yj4tU8TsxkHEr%2Fuploads%2Fgit-blob-c4f0ff453dcf24df58b4328eda50e4b5a5c8194c%2Fdb-mailchimp-bulk-import-toggle.png?alt=media" alt="The Bulk Import page with Action Type Credit, Credit expires Never, Notify Customers off, Send to Integrations on, and a CSV file selected."><figcaption><p>A bulk import reaches Mailchimp only with Send to Integrations turned on.</p></figcaption></figure>

## Disconnect or reconnect

* Click **Disconnect Mailchimp** to stop all sends at once. Events that happen while Mailchimp is disconnected are not sent later. To remove DollarBack's access completely, also remove Dollarback from the authorized apps in your Mailchimp account.
* When you connect again, select the audience and click **Save** again. A new connection can be a different Mailchimp account, so DollarBack does not keep the old audience.

## Common issues

* **The page still shows Not Connected after the Mailchimp window closed**: reload the page.
* **Connected, but no events arrive**: check that an audience is saved under **Audience**. After a reconnect, the audience must be saved again. Then check that the customer is a contact in that audience with the same email address; customers who are not contacts, or who have no email address in Shopify, are skipped.
* **"We couldn't load your Mailchimp audiences"**: DollarBack's access was removed in Mailchimp. Disconnect and connect Mailchimp again.
* **Merge fields are empty**: they update on events only, and on **Sync Balance**. A contact with no credit activity since you connected won't have them yet. Events from before you connected are not backfilled.
* **Bulk-imported credit didn't create events**: the import must run with its **Send to Integrations** toggle on ([Bulk import credit (CSV)](https://help.dollarlabs.io/dollarback-store-credit/analytics-data-and-account/bulk-import-credit-csv.md)).

## Related articles

* [Klaviyo integration](https://help.dollarlabs.io/dollarback-store-credit/integrations/klaviyo-integration.md)
* [Omnisend integration](https://help.dollarlabs.io/dollarback-store-credit/integrations/omnisend-integration.md)
* [Shopify Flow: triggers and actions](https://help.dollarlabs.io/dollarback-store-credit/integrations/shopify-flow-triggers-and-actions.md)
* [Email notifications overview](https://help.dollarlabs.io/dollarback-store-credit/notifications/email-notifications-overview.md)
* [Credit expiry and reminders](https://help.dollarlabs.io/dollarback-store-credit/spending-store-credit-and-rewards/credit-expiry-and-reminders.md)
