MailChimp merge fields can be mapped to any of the WP-Members registration fields in the mail merge fields settings area. This area will indicate all mail merge fields in your MailChimp list, whether they are required fields or not, and what WP-Members field they are mapped to.
Merge fields that are not required do not have to be mapped for subscription to work. However, only merge fields that are mapped to registration fields will have data passed to them when a user subscribes.
If a field is required in MailChimp, that data MUST be passed during subscription or the user will not be added. This means the field must have data associated with it. This means it should be mapped and that field should be required. (The exception to this would be if a specific piece of data is to be set for a specific merge field and that data is generated by a function hooked to the wpmem_mc_merge filter hook, but that’s a more advanced topic for special situations.)
There is a wpmem_mc_merge filter hook in the module for you to use and this can be used to programmatically set values to be tied to specific merge fields.
Creating Merge Fields
Merge fields are created in MailChimp. When you are creating merge fields, you should make careful note of data types used as well as any fields that are required. If the data type is something with a strict structure (essentially any field type other than “text”) then you must make sure that the data that is passed from WP-Members is going to match that data type restriction. Otherwise, the data will not be saved.
If the merge field is set up as a required field in MailChimp, then you must make doubly sure that the data will match because if it does not, the subscription will not be allowed (i.e. it will fail and the user will not be subscribed to the list).
For example, if you create a dropdown field type as a merge field in MailChimp, make note of the saved values (as seen in the screenshot below). In MailChimp, a dropdown (select) field type’s saved values are the same as what is displayed as a selection, as noted in the screenshot.
Mapping Merge Fields
If you have created merge fields in MailChimp and you want to collect that data from the WP-Members registration when the user subscribes, then you will need to make sure those are mapped to a corresponding WP-Members field.
In the MailChimp tab (Settings > WP-Members > MailChimp), below the MailChimp settings you will see any potential merge fields. This table will tell you the field information from MailChimp and whether it is set as a required field in MailChimp.
The last column will be a dropdown selection of all possible WP-Members fields you currently have. If you are mapping a field, select the field you will be collecting this data from. Note that you can create new fields in the Fields tab by selection “Add Field.”
Take careful note of any fields that say “Yes” in the “Required” column. This indicates if they have been set as required in MailChimp. If they are, you MUST make sure that the field you map it to is also set as required in WP-Members. If empty data is passed in a required field, the user will not be subscribed.
Also, if you have a merge field that requires a specific data type (anything other than a text field), make sure that the corresponding WP-Members field has the appropriate pattern recognition or, in the case of dropdown/radio fields, has the correct data values.
Data Values for Dropdown and Radio Fields
MailChimp radio and dropdown field types use the same value to display as they do to save (see the screenshot in “Creating Merge Fields” above). WP-Members assigns these as separate values for these two types of fields, in case the value saved in the database is not necessarily the same as you would display. So you need to take that into account when using these field types. The data value in the WP-Members field MUST match what the possible values are in the MailChimp field.
In the screenshot below, we have the settings for the field we mapped to the MailChimp field “DROPDOWN” above. Note above the possible values of this field with MailChimp.
Avoiding failed subscriptions with dropdown and radio fields
Below, in the WP-Members field settings, take careful note of the possible dropdown values. The first selection in this example (“choice_one”) does not have a possible match in MailChimp. Therefore, if that was selected, there would be no value saved in MailChimp. This is important because if this were a MailChimp required field and that value was selected, the subscription would fail and the user would not be subscribed. Make sure the data types and data values of any merge fields can successfully be passed.
Address Field Format
If you use an “address” field type in MailChimp, it should be noted that is a special field type that is not actually a single field. When passing values as a merge field, it actually needs to be an array of values, with the array keys of each element designated as:
- addr1
- addr2
- city
- state
- zip
- country
See more on the address field type in the MailChimp documentation.
There is a code snippet to help you map your local custom address fields to the MailChimp address field.
Locally Stored Data
When working between the WP-Members Mailchimp Merge Fields tab and your merge fields in Mailchimp, note that the merge field information is queried only once per hour. WP-Members Mailchimp does this to avoid continued and repetitive queries to the Mailchimp API. If you make changes to the Mailchimp merge fields in Mailchimp and then attempt to make changes locally (in WP-Members Mailchimp) but do not see your Mailchimp changes reflected in WP-Members, try clearing the transient values. NOTE: This has nothing to do with front-end processing or user profile processing. It is ONLY in the settings tabs.