Chargebee Retention Field Mapping

Modified on: Thu, 6 Oct, 2022 at 11:17 AM


Why use field mapping in Retention?

When and how can you leverage field mapping in Chargebee Retention by highlighting a few features that it offers?

What are the benefits of field mapping in Retention?


Field mapping allows you to map fields from your enrichment sources to be used in Chargebee Retention experiences, audiences, or data analysis. Enrichment sources come from Chargebee Retention.js or one of our supported enrichment providers.

  • Why use field mapping?
  • Mapped fields in Experiences
  • Mapped fields in Audiences
  • Setting up field mapping
  • Defining fields
  • Finalizing mapped fields from enrichment sources
  • Standard fields

Field mapping enables:

  • Personalization of Chargebee Retention experience
  • Enriched notifications in Slack and Segment
  • Provides benchmarking data consistency
  • Provides enriched Chargebee Retention reporting


Data is retrieved every time the user hits your cancel page where the Chargebee Retention JS lives. We support the following sources for your Fields: Chargebee Retention JS Salesforce, Stripe, Recurly, and ChargeBee Billing. For Salesforce, you can map to any Standard or Custom field on the Account Object. For Stripe, Recurly, and ChargeBee Billing Enrichment we pull back a select set of fields from the subscription record that can be mapped into Chargebee Retention fields. 

Field mapping will be configured per Chargebee Retention Application to allow you to map different fields to support your various use cases. Integrations are also configured per Application now to map cleanly to Fields. 

Using mapped fields in Experiences

Mapped fields are available wherever you see the expression icon, is an area you can use to dynamically present content, add dynamic URL, or present engagement data. 

Pro Tip: Always use a fallback when placing expressions in experiences.  99% of the time the fallback is never used but if a canceler enters your experience a data issue you want the presentation to look polished!

The following headline would grab the canceller's name from Recurly and present it at the time of cancels.  This example below is simple but the possibilities are endless.   

Using mapped fields in Audiences

In addition, mapped fields can be used as Properties for comparison when creating traffic rules for Audiences. For more on that check out our article on defining rules here

Setup field mapping

To set up Field Mappings, navigate to Chargebee Retention Settings on the left-hand navigation bar. Find the field mappings section and click Map fields. 

Pro Tip: Map fields with caution! If you remove any of the mapped Fields, you will lose that data source!

Defining fields sent through Chargebee Retention.js

By default, fields sent through Chargebee Retention.js are automatically detected but not mapped. To map them first click View all fields.

You will be presented with a field mapping modal that displays the discovered fields, standard fields, and an option to add a custom field. 

Look for the field you would like to map and give it a meaningful name.  Remember to choose the correct field type. After you have saved imported fields, give it a display name you will remember and create the mapping to be used in Chargebee Retention experiences.

Pro Tip: Choose the correct field type! Chargebee Retention provides numeric operators, URL validation and Date comparison to be used for Audience Targeting. Choosing the wrong field type here can yield incorrect traffic routing. 

If you are working offline with your engineering team and our server has not picked up new fields yet, you can always manually create the field to prep for incoming sessions.  You'll need to know the exact syntax of what will be sent over so be sure to sync with your development team. 

After you have defined the fields coming from your Chargebee Retention.js snippet click save and get starting on mapping fields for use. 

Finalizing mapped fields

After you've defined your fields sent through the Chargebee Retention.js snippet you can now map them for use in Chargebee Retention. Start by giving your fields a descriptive name so you can easily pick them from the expression and property dropdown selects.  

Type a name, select the field type and choose the source. You'll notice all of your enrichment sources in the drop-down. 

Standard fields

A  Standard Field Mapping maps directly to the Standard Fields on the JS Snippet. For a list of default Standard Fields, see our guide on Installing the JS Snippet.  Optionally you can swap these out for fields captured from your enrichment provider.  In the following image, you'll see we've mapped the Salesforce Account Name to one our standard fields. 


Please email us if you have any questions or concerns. 

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.