Populate Custom Fields in Zuora

Zuora custom fields let you capture additional information on objects such as Accounts, Subscriptions, and Orders, tailored to your business requirements. These fields provide flexibility to store custom attributes that aren't available by default in Zuora.

Limio supports the automatic population of Zuora custom fields during key events, such as new orders, subscription switches, and cancellations, making it easier to pass data from the customer journey into Zuora.

There are three ways to populate custom fields in Zuora via Limio:

Method	Use Case	Configuration
A. Catalog Configuration	Populate fields using metadata from a Page or Offer	No-code, via templates
B. Modular Checkout	Capture user input via Field subcomponents	No-code, via checkout config
C. General Settings	Map order data to Zuora fields per order type	No-code, via Settings UI

---

A. How to configure from your Limio Catalog configuration

1. Configure the custom field in Zuora

To enable Limio to populate custom fields, it's crucial to define them in Zuora first. Supported custom fields include those related to the following Zuora objects:

• Subscriptions

• Orders

• Account

Consult the Zuora documentation for a step-by-step guide on setting up your custom fields.

It's important to note that custom fields populated by Limio or Limio for Salesforce should adhere to a specific API naming convention. The API Name must begin with ltm_ and have __c appended at the end. E.g. ltm_fieldName__c. Field Label in Zuora however has no restriction nor impact in Limio.

Custom field defined in Zuora

For detailed insights into the full use of ltm_ tags refer to our documentation on Configure Tracking in Salesforce and Zuora.

2. Sync the Zuora Product catalog

To ensure Limio includes the custom field in the order sent to Zuora, Limio must first be aware of the custom fields defined in Zuora, and which objects they are on.

Initiate the Catalog Sync process in the Limio app. For step-by-step instructions, refer to our guide on how to Sync Between Limio and Zuora Catalogs

For lmo and utm parameters, you are now done. lmo are always added via the URL. utm parameters will be added via the call to action on the referrer, for example via ?utm_content=page123.

For ltm parameters, do step 3 to 5.

3. (ltm parameters only) Add the custom attribute to the template

To define custom attributes in Limio, follow this guide on how to create new custom attributes. In order for the custom attribute to be passed to Zuora they must match the API without __c appended on the end. You do not need to put information about the Zuora object.

Please be mindful that these attributes are case-sensitive. Refer to the example below for clarification:

Custom field defined on the Limio Template

4. (ltm parameters only) Add the custom field to the page/offer

Once added to the relevant offer/page template, the new field will appear on offers/pages using that template. You can then simply enter the desired field value and save the page.

5. (ltm parameters only) Publish the page

Changes will only be reflected on new events after the relevant pages have been published.

OOTB custom fields

Some custom fields come pre-configured and don't require setup in Limio. As long as these fields are defined in Zuora, they will automatically be populated. Explore further details in our guide on Out-Of-The-Box Zuora Custom Fields.

Date type custom fields

To utilize date functionality as a custom field in Zuora for purposes like defining a delayed subscription start date, follow these steps:

1. Define the custom field in Zuora, selecting "Data Type: Date."

2. In the Limio template, define the custom field as "Type: string."

3. When specifying the custom field value, input a string in the format YYYY-MM-DD.

By adhering to these steps, the custom field will be captured as a date in Zuora, displayed according to the format defined in your Zuora settings.

---

B. How to configure from your Limio Modular Checkout

Populating Zuora Subscription Fields

You will need to use a specific Subcomponent: Field in Limio's Modular Checkout and respect some naming conventions. Learn more Form Subcomponent: Field.

Populating default Zuora contact fields

In addition to custom fields, Limio also supports the automatic population of default Zuora contact fields, such as email, phone number, and address details. These can be updated during order submission to keep billing information accurate and up to date.

To learn how to configure and populate these standard fields using Limio's out-of-the-box components or custom SDK integrations, see our guide: Update Contact Details in Zuora

Populating any fields in Zuora (requires code)

As part of the Limio SDK, you can use the updateCustomField method to define a custom field and map it to Zuora. For example, if you want to map a custom field named UserID on the Zuora Account object, pass 'UserID.account' to this method.

➡️ Read more in the developer documentation

---

C. How to configure from General Settings

Use Settings > Zuora > Custom Attributes to map order data directly to Zuora custom fields. This method is useful when you need to:

• Pass tracking data or order metadata to Zuora

• Set static values on Zuora objects

• Configure different mappings per order type (new, cancel, switch, etc.)

Prerequisites

1. Custom field must exist in Zuora (see Step 1 in Method A)

2. Catalog Sync must be completed (see Step 2 in Method A)

Configuration Structure

The setting is organised by Zuora object type:

• Order Custom Attributes - Fields on the Zuora Order object

• Subscription Custom Attributes - Fields on the Zuora Subscription object

• Account Custom Attributes - Fields on the Zuora Account object

Each object type contains an array of configurations, one per order type.

Setting Up a Custom Attribute Mapping

Field	Description	Example
Order Type	When this mapping applies	new, change_offer, cancel_subscription
Zuora ID	The custom field API name in Zuora	ltm_CampaignCode__c
Attribute Type	How to format the value	string, number, date
Use a path?	Extract from order data (true) or use static value (false)	true
Path	Dot-notation path to value in order	tracking.campaignCode
Value	Static value (when Use a path = false)	Limio

Supported Order Types

Order Type	When It Applies
new	New subscription purchases
change_payment	Payment method updates
cancel_intent	When customer initiates cancellation
add_offer	Adding an additional subscription
change_address	Delivery/billing address changes
change_offer	Switching to a different offer
cancel_subscription	Full subscription cancellation
suspend	Pausing a subscription
resume	Resuming a paused subscription

Attribute Types

Type	Description	Example Input	Output
string	Text value	123	"123"
number	Integer	"42"	42
float	Decimal number	"3.14"	3.14
date	ISO date string	"2024-01-15"	Parsed date
null	Always null	any	null
any	Pass through unchanged	{ foo: "bar" }	{ foo: "bar" }

Example 1: Campaign Code from Tracking

Pass the campaign code from URL tracking to the subscription:

Configuration:

Field	Value
Order Type	new
Zuora ID	ltm_CampaignCode__c
Attribute Type	string
Use a path?	true
Path	tracking.campaignCode

Input order:

{
  "order_type": "new",
  "tracking": { "campaignCode": "SUMMER2024" }
}

Result on Zuora Subscription: ltm_CampaignCode__c = "SUMMER2024"

Example 2: Static Source Value

Always set the source to "Limio" for new orders:

Configuration:

Field	Value
Order Type	new
Zuora ID	ltm_Source__c
Attribute Type	string
Use a path?	false
Value	Limio

Result: ltm_Source__c = "Limio"

Example 3: Account-Level Acquisition Date

Store the order creation date on the account:

Configuration:

Field	Value
Order Type	new
Zuora ID	ltm_AcquisitionDate__c
Attribute Type	date
Use a path?	true
Path	created

Common Paths Reference

Path	Description
tracking.campaignCode	Campaign code from URL
tracking.utm_source	UTM source parameter
tracking.utm_medium	UTM medium parameter
tracking.utm_campaign	UTM campaign parameter
created	Order creation timestamp
customer.email	Customer email
customer.firstName	Customer first name
billingAddress.country	Billing country

---

Automatic Attribute Extraction

In addition to the three configuration methods above, Limio automatically extracts certain custom fields from order data during processing.

From URL Tracking (order.tracking)

Fields matching these patterns are automatically included:

Pattern	Source
ltm_*__c	Limio tracking markers
utm_*__c	UTM parameters
lmo_*__c	Limio offer markers

From Offer Attributes

Fields matching ltm_*__c are automatically extracted from:

• order.orderItems[].offer.data.attributes - for new orders

• order.offer.data.attributes - for offer changes

Validation

Automatic extraction only includes fields that exist as custom fields in your Zuora tenant (validated against the synced catalog).

---

Processing Flow

The diagram below shows how custom attributes flow from configuration to Zuora:

┌─────────────────────────────────────────────────────────────┐
│                    Order Submitted                          │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│              Custom Attribute Processing                    │
│                                                             │
│  Phase 1: General Settings mappings                         │
│  ├─ Load zuora.custom_attributes from Settings              │
│  ├─ Match order.order_type to configuration                 │
│  ├─ Extract values via path OR use static value             │
│  └─ Format by type (string, number, date, etc.)             │
│                                                             │
│  Phase 2: Automatic extraction                              │
│  ├─ Extract ltm_/utm_/lmo_ from order.tracking              │
│  ├─ Extract ltm_ from offer attributes                      │
│  └─ Validate against Zuora custom field definitions         │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│              Merged attributes sent to Zuora                │
│                                                             │
│  Applied to:                                                │
│  • Account creation/update                                  │
│  • Subscription creation/update                             │
│  • Order creation                                           │
└─────────────────────────────────────────────────────────────┘

---

Caveats and Important Notes

Custom Fields Must Exist in Zuora First

The custom field (e.g., ltm_CampaignCode__c) must be created in Zuora and synced to Limio before use.

Naming Convention is Critical

• API Name must start with ltm_ and end with __c

• Names are case-sensitive

• Limio template attributes omit the __c suffix

Path Must Be Valid (Method C)

If usePath: true and the path doesn't exist in the order, the attribute is omitted from the Zuora request.

Order Type Matching (Method C)

Configuration only applies when order.order_type matches exactly. Create separate configurations for each order type needed.

Type Conversion (Method C)

• number with non-numeric input returns NaN

• float with non-numeric input returns NaN

• date with invalid input returns invalid date

Merge Precedence

When the same field is configured via multiple methods, the precedence is:

1. Automatically extracted values (highest priority)

2. General Settings mappings

3. Catalog/Offer attributes

---

Troubleshooting

Attribute Not Appearing in Zuora

1. Verify the custom field exists in Zuora with correct naming (ltm_*__c)

2. Run a Catalog Sync in Limio

3. Check the order_type matches your order (for Method C)

4. Verify the path exists in order data (for Method C)

5. Publish any page/offer changes (for Method A)

Wrong Value Type

Ensure the attribute type setting matches what Zuora expects. Zuora may reject requests with incorrect types.

Missing Tracking Data

Tracking data (ltm_*, utm_*, lmo_*) is only available if:

• Passed via URL parameters to the shop

• Shop correctly captured it in order.tracking