Custom Fields

Introduction

Recurly provides the option of creating custom fields for the Account, Charges, Item, Plan, and Subscription objects. You can use this option to track information about a customer or their subscription objects in Recurly, to capture additional item attributes in your item catalog, or enable offering plans based on specific criteria.

Definition of the Custom Field object must be created via the Recurly Admin Console (UI) whereas assignment, editing or viewing can be via the API or the Recurly Admin Console (UI).

Custom Fields Availability by Recurly Plan Level

The number of custom fields which can be added to Recurly records is limited by the Recurly plan level you are using and the environment. For Recurly 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 5 custom fields to your Recurly site.

Elite

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

Exporting Custom Field Data

Custom field data is available in the Accounts, Adjustments, 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.

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, item, plan, or subscription.

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

When you create a new custom field, you will see a screen similar to below:

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, charge, item, plan, or subscription object.
• Admin Console Access: this option will govern how the field behaves in the Recurly UI.
  Hidden in the admin console - the field is only editable or viewable via API.
  Read-only in the admin console - the field is viewable in the UI, but only editable in the API.
  Editable in the admin console - the field can be viewed and edited in both the UI and API.
  Able to set in the admin console (applicable only to Charge) - enables the field to be set, but not viewed, in the Admin console
• Admin Console Field Name: if you select an option to enable the field to be set, edited or viewed in the Admin Console, this field is required and the value becomes the field name the Admin Console.
• Tooltip Description: if populated, an ? icon will appear next to the Admin Console Field Name and provides a means to add context to the field for users to understand the fields purpose.

You can also view a site's custom field definitions as well as get an individual custom field definition via API. Learn more v3 and Learn more v2

Custom Field Data Types

• All custom fields are limited to 255 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 picklist, 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 behaves in the Recurly Admin Console UI.
  Hidden in admin console - the field is only editable or viewable in the API.
  Read-only in the admin console - the field is viewable in the UI, but only editable in the API.
  Editable in the admin console- the field can be both viewed and edited in the UI and API.
  Able to set in the admin console (applicable only to Charge) - enables the field to be set but not viewed in the UI
• Admin Console Field Name: if you select to allow the field to be set, edited or viewed in the Admin Console, this field is required and the value becomes the field name in the Admin Console.
• Tooltip Description: if populated, an ? will appear next to the Admin Console Field Name and provides a means to add context to the field for users to understand the fields purpose.

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, charges, items, plans, or subscriptions you can remove this data completely from your Recurly site.

• Navigate to Configuration > Custom Fields.
• Make note of the value in the column titled Field Name (API).
• Hover over the row of the custom field you'd like to eliminate and on the right side of the table select Delete.
• Enter the value you made note of and the Confirm button will become enabled.

❗️

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 loose this Sales Rep data for the 100 accounts when you delete the Sales Rep custom field definition.

This delete is permanent and cannot be undone and will happen as soon as you press Confirm so be sure you truly want to delete the field.

Custom Fields on an Account

Use this option to create custom field values for the Account 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

When defining the custom field object, if you selected the option to it editable in the UI, you can set those values via the UI when creating or editing an account:

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 Charges

Use this option to create custom field values for the Charge object when you wish to set a custom value on non-subscription line item charges/credits. This value can be set through a Line Item (charge or credit) or through a Purchase. Defining and setting a value for a Charge object also enables a merchant to trigger off this field for sending more tailored email communications.

Recurly Charges UI

When defining the custom field object, if you selected the option for 'Able to set...', you can set those values via the UI by pulling up a customer's account, selecting to Add Charge/Item or Add Credit and scroll to the bottom of the page, just above the Add Another Charge button. The name will be whatever you defined for Admin Console Field Name. In the example below it was CHARGECUSTOMFIELD. Once set, the data will only be viewable via an API call.

Recurly Charges API

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

You can write custom field data to a line item with a POST to Line Items or Purchases.

You can read custom fields data in GET calls for Line Items, Purchases and Invoices. You will see a Custom Fields array as part of the Line Items array. Below is sample code for the v3 API.

"line_items":[
    {
    "currency": "USD",
    "unit_amount": "1.05",
    "type": "charge",
    "quantity": 1,
  "custom_fields": [
    {
      "name": "Foo",
      "value": "bar"
    }
  ]
}

Learn more v3 api.

Learn more v2 api.

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

When defining the custom field object, if you selected the option to it editable in the UI, you can set those values via the UI when creating or editing a subscription:

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 Fields on an Item

Use this feature to create custom field values for the Item object if you need to collect additional item information. Examples of custom fields on items:

• Product variant information (e.g. size, color)
• Product family / category
• Sales channel
• Sales region

Recurly Item UI

When defining the custom field object, if you selected the option to it editable in the UI, you can set those values via the UI when creating or editing an item:

When defining the item object, if you selected the label as read-only in the UI, the field values will be readable via the view item screen but will not present on the edit item screen.

Recurly Item 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 item with a GET call.

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

<item>
  <custom_fields>
    <custom_field>
      <name>foo</name>
      <value>asdf</value>
    </custom_field>
  </custom_fields>
</item>

Custom Fields on a Plan

Use this option to create custom field values for the Plan object when the information you need is account-specific. Examples of custom fields on a plan:

• Customer region or location (US vs Europe or California vs New York)
• Specific Customer Channel
• New or returning customer
• Tax purposes

Recurly Plan UI

When defining the custom field object, if you selected the option to be editable in the UI, you can set those values via the Admin UI when creating or editing a plan:

When defining the plan object, if you selected the option for as read-only in the UI, the field values will be readable when viewing the plan but will not be present on the edit plan screen.

Recurly Plan 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 write custom field data to an individual account with a PUT or POST to plans.

You can read custom fields on all plans or an individual plan a GET plans call.

Learn more v2 api
Learn more v3 api

FAQ

• Emojis are not allowed 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.
• Recurly will delete any values which appear to be credit card numbers or CVV codes which are entered in custom fields. These values will never be stored in order to maintain PCI compliance.
• An Item and Plan export is not currently offered; therefore custom field data on Items or Plans is not available via export.