The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Custom Fields

Custom fields add context to your Recurly account or subscription data. Use them to track unique identifiers from other systems or add data to make your Recurly data more relevant and useful.

Introduction

Recurly provides the option of creating custom fields for the Account and Subscription objects. You can use this option to track information about a customer or their subscription objects in Recurly. Custom fields can be edited and viewed via the API or the Recurly Admin Console (UI).

Recurly merchants on the Pro and Enterprise plans can use custom fields.

Creating Custom Field Definitions

Users with the Configuration role can create custom field definitions on their Recurly site. A custom field definition will enable Custom Field Values to be collected on the account or subscription.

Navigate to Configuration > Custom Fields > Create Custom field to begin the process.

When you create a new custom field, you will see the following screen:

These fields are available on the custom fields definition:

  • API Field Name: this is the ID which will be used in the API to refer to this custom field. This field cannot contain spaces and can only use numbers, letters, dashes, and underscores.
  • Recurly Object: this will govern the object on which the Custom Field is created - either the account or subscription object.
  • Admin Console Access: this option will govern how the field appears in the Recurly UI. Choosing to hide the field from the Admin Console will make the field only editable or viewable in the API. Choosing "Read-only in the Admin Console" will make the field viewable in the UI, but only editable in the API. Selecting "Editable in the Admin Console" will allow the field to be viewed and edited in both the UI and API.
  • Admin Console Field Name: if you select to allow the field to be edited or viewed in the Admin Console, it is required to pass a name for the field in the Admin Console.
  • Tooltip Description: this field will be shown in the Admin Console to add context to the field for users to understand the purpose of the field.

Custom Field Values on an Account

Use this feature to create custom field vlaues for the Accounts object if you need to collect customer-specific information. Examples of custom fields on accounts:

  • Subscriber ID from other business systems
  • Sales representative name
  • Channel partner name
  • Subscriber segment (e.g. small / medium / large)
  • Subscriber region

Recurly Account UI

If you select the option to make custom field data editable in the UI when creating a custom field definition, you can navigate to an account and enter data in the custom fields:

This data will then be readable on the account record in the right-hand sidebar in the UI:

If you select the option for custom fields to be read-only in the UI, the field values will be readable via the admin sidebar but will not present on the edit account screen.

Recurly Account API

The API for custom fields will be available to your site regardless of whether or not you allow the custom field to be viewed or edited in the Recurly UI.

You can read custom fields on an individual account with a GET call. This functionality is available beginning in API version 2.14.

You can write custom field data to an individual account with a PUT or POST call through the API.

<account>
  <custom_fields type="array">
    <custom_field>
      <name>foo</name>
      <value>asdf</value>
    </custom_field>
  </custom_fields>
</account>

Custom Fields on a Subscription

Use this option to create custom field values for the Subscription object when the information you need is subscription-specific. Examples of custom fields on subscriptions:

  • Customer device ID (for IOT businesses)
  • Acquisition channel
  • Customer segment
  • Subscription ID from other systems (can be used to do payouts on a subscription basis)
  • Partner ID who helped to acquire the customer

Recurly Subscription UI

If you select the option to make custom field values editable in the UI when creating a custom field definition, you can navigate to a subscription and enter data in the custom fields:

After editing these field values, you will be able to see them on the subscription screen in the Recurly UI. This information is also available on the subscription view on the account screen.

Recurly Subscription API

The API for custom fields will be available to your site regardless of whether or not you allow the custom field to be viewed or edited in the Recurly UI.

You can read custom fields on an individual subscription with a GET call.

You can write custom field data to an individual subscription with a PUT or POST call through the API.

The subscription POST call can be made while creating the subscription. This functionality is available beginning in API version 2.14.

<subscription>
  <custom_fields type="array">
    <custom_field>
      <name>foo</name>
      <value>asdf</value>
    </custom_field>
  </custom_fields>
</subscription>

The subscription PUT call functions through the subscriptions/notes route so that it will not collide with other changes being made on the subscription. This functionality is available beginning in API version 2.14.

<subscription>
 <terms_and_conditions>Payment can be sent to Acme Cloud, Inc.</terms_and_conditions>
 <customer_notes>Thanks for your business!</customer_notes>
 <vat_reverse_charge_notes>No VAT was applied on this invoice. Please reference this legislation.  </vat_reverse_charge_notes>
 <custom_fields>
  <custom_field>
    <name>food</name> <!-- set to the appropriate name -->
    <value>taco</value>
  </custom_field>
 </custom_fields>
</subscription>

Custom Field Data Types

  • All custom fields are limited to 100 characters and are available as text fields only.
  • You can populate these fields with any series of letters and numbers (e.g. "xyz123" or "John Smith" or "こんにちは.").
  • There is currently no support for fields which are picklists, boolean, true/false, or radio buttons.

Editing Custom Field Definitions

After creating a custom field definition, you can edit some data elements on the definition through the Configuration > Custom Fields menu:

  • Admin Console Access: this option will govern how the field appears in the Recurly UI. Choosing to hide the field from the Admin Console will make the field only editable or viewable in the API. Choosing "Read-only in the Admin Console" will make the field viewable in the UI, but only editable in the API. Selecting "Editable in the Admin Console" will allow the field to be viewed and edited in both the UI and API.
  • Admin Console Field Name: if you select to allow the field to be edited or viewed in the Admin Console, it is required to pass a name for the field in the Admin Console.
  • Tooltip Description: this field will be shown in the Admin Console to add context to the field for users to understand the purpose of the field.

You cannot edit the API Field Name or the Recurly object on which the custom field resides.

Deleting Custom Field Definitions

If you would like to no longer collect a certain custom field on your accounts or subscriptions, you can remove this data completely from your Recurly site. Navigate to Configuration > Custom Fields. Select the custom field you'd like to eliminate and click Options > Delete Custom Field.

Deleting a Custom Field Definition

Deleting a custom field definition from your site will cause all associated custom field data to be deleted. For example, if you are storing a custom field for Sales Rep which is populated with names on 100 accounts, you will lose this data for the 100 accounts when you delete the Sales Rep custom field definition.

This deletion is permanent and cannot be undone.

Make sure you are certain about what you are deleting before taking this action.

Custom Fields Definition by Plan

The number of custom fields which can be added to Recurly records is limited by plan. For exact plan definitions, see here.

Sandbox and Developer Modes

In sandbox and developer modes, you can add 5 custom fields to your account. This is meant to help you test the feature and ensure that your integrations are built to use this information accurately.

Core

Custom fields are not available in the Core plan of Recurly. If you have custom fields enabled in sandbox mode and promote to core, you will need to delete your custom fields in order to upgrade.

Pro

On the Recurly Pro plan, you can add 3 custom fields to your Recurly site.

Enterprise

On the Recurly Enterprise plan, you can add 5 custom fields to your Recurly site.

Exporting Custom Fields Data

Custom field data is available in the Accounts and Subscriptions exports.

Your custom fields will always appear as the final columns to the right in each export. If other fields are added by Recurly to the exports, the custom fields will continue to be the final fields on the right in subsequent export versions.

FAQ

  • Emoji are not alllowed and will be stripped in the API or will pass an error in the UI. If you pass an emoji, Recurly will not save that emoji to our database but will save all other characters.
  • There is not currently support for searching in the Recurly UI for custom field values.
  • The Recurly for Salesforce integration does not currently support passing custom field values from Salesforce to Recurly.