Custom Fields and Metadata

Chargebee lets you create custom fields for customers, subscriptions, features, product families, plans, addons, price points, and coupons. After creation, you can add these fields to Chargebee Checkout pages and invoices. You will also be able to access them via the web interface or API.

Custom Fields for Customers

Use the option to create custom fields for the Customer object if you need to collect customer-specific information, such as date of birth, age, or gender.

Custom Fields for Subscriptions

Use the option to create custom fields for the Subscription object when the information you need is subscription-specific, and your customers have multiple subscriptions. E.g., Domain URLs, Phone numbers, Tracking IDs, Shipping dates, T-shirt sizes.

Custom Fields for Invoices/Credit Notes

Use this option to create custom fields for the Invoice or Credit note object when the information you need is specific to a particular Invoice or Credit note, and cannot be created at a Customer or Subscription level. E.g., Approved by, Additional status, Collection agency name, Expected date of collection, and so on.

Custom Fields for Features

Use this option to create custom fields for the feature entity, enabling you to capture additional information such as the feature type, version, and other relevant details.

Custom Fields for Product Families

Use this option to create custom fields for the Product Family entity to capture additional information for your product families such as the list of products that form a part of the product family, or to add a point of contact for each product family.

Custom Fields for Plans/Addons/Price Points

Use this option to create custom fields for your plans, addons, and charge price points to store specific information related to them (like which country the price is available in) for your future reference. The information, once captured, is displayed in the respective price points' create, edit, and details pages.

Custom Fields for Coupons

Use this option to create custom fields for your coupons to store specific information related to them (like which marketing campaign they belong to or the geographic region they're applicable in) for your future reference. The information, once captured, is displayed in the respective coupons' create, edit, and details pages.

Types of Custom Fields

The supported custom field types are:

• Single-line text: This field will appear as a text box, and the maximum character limit is 99.

• Multi-line text: This field will appear as a text area, and the maximum character limit is 250.

• Dropdown: This field type will appear as a dropdown menu. You can add as many options as you'd want, but ensure that the total number of characters used for all the options put together, does not exceed 5000.

• Checkbox: Use this field type to create checkbox options. The default value of this field type is false.

• URL: This field type will appear as a text area. The URL provided here will be validated for "http://" and "https://".

• Email: This field type will appear as a text box. The email address will be validated.

• Date picker: Use this field type if you want to collect date-related information.

• Timestamp: If you need to collect information related to date as well as time as a timestamp, use this field type.

• Numbers: You could use this field type for collecting information such as phone number. This field does not accept input other than numbers.

You can add up to 50 custom fields for each supported object. The breakdown is as follows:

• 30 String fields (includes single line text, multiline text, dropdown, checkbox, URL and email)
• 5 Date fields
• 5 fields of the type Timestamp
• 10 fields of the type Numbers

Creating Custom Fields

To create custom fields in your Chargebee site, go to Settings > Configure Chargebee > Custom Fields in your TEST site. A toolbox is available for creating the fields you require:

1. Create Custom Field in Test Site: Select the field type from the tabs and fill in the details in the field creation screen that appears:

• Field Label: Text that will appear on the UI for Chargebee Checkout pages and invoices.
• API Name: Field reference for API calls and merge fields.

The custom fields are considered active, and are available only on the test site. Publish the fields to your live site to include custom field information in the invoices that you send to your customers, or in Chargebee Checkout pages viewed by them. Check how the fields work for your use cases before pushing them to your live site.

2. Publish Custom Field to Live Site: In the Custom Fields main page, click Publish to Live and confirm changes.

The custom fields will now be available on your LIVE site. To manage how they appear in Chargebee Checkout:

If you're using In-App Checkout, navigate to Settings > Configure Chargebee > Custom Fields to make further changes in the LIVE site.

Archive and Unarchive Custom Fields

You can archive active custom fields. Open the required custom field, and click the Archive button available on the top right corner. The field will be listed under the Archived section in the main Custom Fields page.

Archiving changes the field's status only; it does not discard existing custom field data. You cannot link an archived field to additional modules, but existing linked custom fields continue to display. Archived custom fields continue to count toward the custom field limit.

To unarchive, open the archived field and click the Unarchive option available on the top right corner.

Discarding or Deleting Custom Fields

Archived custom fields that have not been synced to the live site can be discarded. Open the archived field, and click the Discard Field option available on the top right corner.

You can delete an archived custom field permanently from your test site using the Discard option if it has not been synced with the live site.

Discarding Changes Made to Custom Fields

You can discard changes you have made to existing custom fields that have also been pushed to the live site. Open the modified field, and click the Discard Changes option available on the top right corner.

Rolling Back Changes Made to Custom Fields

Clicking Rollback changes will discard all changes that have not been published to your Live site. If you have created new fields but have not pushed them to your live site, they will also be discarded.

Adding Data to the Custom Fields

Once the custom fields have been added to your site, you can add data to them by editing or creating records for the objects that have custom fields.

For example, to add data to a custom field for an existing customer, open the customer details page and use the Edit Customer option. This will display all the custom fields that are available in your site and you can add the data here.

You can capture custom field data during sign up through Chargebee Checkout, using the API or through the web interface.

Capturing custom field data via Chargebee Checkout

You can collect the custom field data via Chargebee Checkout. Make sure to enable the custom field created for the customer portal.

Updating custom field data through the customer portal

By default, the custom field that you create will be in Hide and Non Editable state in the customer portal. If you'd like to make these fields visible on the customer portal or make them editable, change your preferences as explained in Configure Fields and Labels. Your customers can now log in to their customer portal and update the data for your custom fields.

Using the API to collect custom field data

For API users, if you have custom fields created in your Chargebee site, they will be listed in your API documentation as part of your input parameters. These fields are visible only when you are logged in to the same Chargebee site where they were created. For example, if you are not logged in, these fields will not be shown under Customers → Customer attributes.

Adding custom field data through the web interface

When creating a new subscription or a customer using the web interface, the list of custom fields will be displayed in the creation page.

Reordering Custom Fields

The custom fields you've created can be reordered to make data entry logical for your customers.

In-App Checkout

If you're using In-App Checkout, custom fields can be reordered by placing the field in the right position. Navigate to Settings > Configure Chargebee > Checkout and Self-Serve Portal > Fields.

Grouping Custom Fields

Grouping lets you move custom fields into the relevant Chargebee Checkout and Self-Serve Portal section, such as Account Information, and place related fields together. Go to Settings > Configure Chargebee > Checkout and Self-Serve Portal > Fields, then drag and drop fields into the order you want. For details, see Configure Fields and Labels.

Viewing Custom Field Data

Once the data for the custom fields is captured and stored, it appears on the detail section of the respective page.

For example, the data captured for custom fields created in Customer Object will appear in the Customer Details section.

Search and Filter with Custom Fields

The custom fields created for your site will be available in the filter section when you search or filter customers/subscriptions.

Custom fields will also be available as mail merge fields and can be used in your email notification templates.