Skip to content

Email Service Integration - MailChimp - Subscription tagging

Target Audience: Developers, Stakeholders

Creating your MailChimp account

In order to get started with your first subscription tagging through MailChimp, a MailChimp account naturally has to be created. You can create a free MailChimp account here.

Fetching your API key

In order for Payway to be able to notify MailChimp about updated subscription tags, an API Key is required.

In order to obtain your MailChimp API key, navigate to Profile => Extras => API keys => Create A Key and follow the on-screen instructions. Be sure to save your generated API key somewhere safe, as you will need it later.

Configuring your sending domain

Having the MailChimp account created and the API key fetched, we can now move on to configuring your sending domain. This is a process that validates that you, in fact, own the domain that you say you do, and allow email's to be sent from that given domain.

In order to configure your sending domain, perform the following steps:

  1. From within MailChimp, navigate to Profile => Domains => Add & Verify Domain.
  2. Enter an email address belonging to the domain you wish to send your email from.
  3. Follow the on-screen guide provided by MailChimp to verify your domain. This will require changes to your DNS records.

Configuring your audience

In order to start syncing your customers subscription tags between Payway and MailChimp, we must know what the relation between Payway and MailChimp looks like.

In order to configure this relation, perform the following steps:

  1. From within MailChimp, navigate to Audience => All contacts. If you have multiple audiences, make sure you select the correct one!
  2. Select Settings => Audience name and defaults, and take note of the Audience ID. Save this ID somewhere safe, as you will need it shortly.
  3. From within the Payway Administration Portal, navigate to Control panel => Tags => Create tag.

The name of the tag should correspond according to the following format:

mc:add:<TAG_NAME>:<AUDIENCE_ID>

For example, if you would like to add the "digital" tag to the customer when a subscription is created, it would look something like this:

mc:add:digital:abc123
Key Description
TAG_NAME The name of the tag that should be applied to the customer.
AUDIENCE_ID The Audience ID fetched from MailChimp in the previous step

Once you have created the tag as you like it, simply apply the tag to one or more packages of your choosing.

Subscription behaviour

The tags you configure have different behaviour depending on which event is triggered from Payway. You can read more about these behaviours below.

Purchasing a subscription

When a customer purchases a subscription, we will collect all of the tags configured on the underlying package of the subscription and make sure the customer also has these tags in MailChimp.

Renewing a subscription

When a customer has an existing subscription that is renewed at the end of their current period, we make sure all the tags are up-to-date. In other words, if any tags have been added to the underlying package since the subscription was initially purchased, these will be exported to their MailChimp profile.

Activating a pending subscription

When a customer has an existing subscription with a future start date, the configured tags of the underlying package will not be exported until the subscription is activated.

Sharing a subscription to another account

If a customer decides to share their subscription to friends or family, the receiver of the subscription will receive the same tags in MailChimp as if they had the subscription themselves. If the subscription sharing is ever removed, the receiver of the subscription sharing will lose their MailChimp tags accordingly.

Note that the tags for the receiver will not be exported until the subscription sharing is accepted.

Deactivating a subscription

When a customer deactivates their subscription, we will collect all of the tags configured on the underlying package of the subscription and make sure the customer no longer has any of these tags in MailChimp. In other words, we undo the changes we made to the customer in MailChimp whenever the subscription was purchased.

Practical example

  1. Customer purchases a subscription, where the underlying package has the mc:add:digital:abc123 tag configured.
  2. If the customer does not exist in your MailChimp, a representation of the customer is created.
  3. We export the digital tag to the abc123 audience in MailChimp, for the given customer.
  4. The customer decides to share their subscription with their friend, Jane. A MailChimp profile for Jane is created if she does not already have one, and then receives the digital tag within the abc123 audience.
  5. A few months later, the customer decides to cancel their subscription, and upon deactivation, we remove the digital tag from the abc123 audience in MailChimp from both the subscription holder and from Jane.

Creating your first tag

Once you have gotten this far, you're almost through the finishing line!

Now, all that remains, is to simply contact our support. Information that must be included in this request are:

  • Your Mailchimp API Key
  • Your sender email address (the email address that your email's should originate from)

Once your support request has been sent and we have had time to process it, you can start sending your first emails from MailChimp!