Complex collections let you filter segments on repeating records, such as a user's subscriptions. Use them to target users based on subscription-level detail like plan, status, and price.

Available on all Recurly plans

1Definition 2Key benefits 3Key details

Prerequisites

You must have Company or App Administrator permissions in Recurly Engage.
You should be familiar with building segments. See Overview: segments.

Limitations

Filters on different sub-attributes within the same collection are evaluated independently, which can produce broader matches than you expect. See Filtering behavior below.

Definition

Most traits hold a single value per user, such as a plan code, a lifetime value, or a signup date. A complex collection is different: it's a set of repeating records per user, where each record has its own sub-attributes.

Subscriptions are the collection type available today. A single user can have more than one subscription record, for example one active plan and one expired plan, and each record carries its own plan, status, price, and renewal dates. Complex collections let you filter on those sub-attributes when you build a segment.

Key benefits

Richer targeting Filter on subscription-level detail, such as plan, status, and price, rather than a single flattened value per user.

Handles multi-subscription users Represent users who hold more than one subscription, at once or over time, instead of exposing only their most recent one.

Composable filters Add multiple sub-attributes to the same collection filter to narrow a segment further.

Key details

Build a filter on a complex collection

Select Subscriptions

In the segment builder, select Subscriptions from the trait dropdown.

Choose a sub-attribute

Choose the sub-attribute you want to filter on. This is the specific dimension within the collection, such as plan, status, or price.

Set the match type

Set your match type and criteria for that sub-attribute.

Add more sub-attributes

Add more sub-attributes to the same collection filter to refine it further.

Filtering behavior

Filters on different sub-attributes within a subscription collection are evaluated independently across all of a user's subscription records, not against a single matching record.

This means a user qualifies if any of their subscriptions matches criterion A and any of their subscriptions matches criterion B. Those can be two different subscriptions. The filter doesn't require both conditions to be true on the same record.

Example

Say you build a segment with two subscription filters:

Plan = Premium
Status = Expired

A user with these two subscription records would match this segment:

Subscription	Plan	Status
A	Premium	Active
B	Basic	Expired

No single subscription of this user's is both Premium and expired, but the user still matches. Subscription A satisfies the Plan filter, and subscription B satisfies the Status filter, independently of each other.

Why this mattersIf your intent is "users whose Premium subscription has expired," this filter setup also captures users like the one above, whose Premium subscription is still active and whose expired subscription was a different, unrelated plan. Build and review segment membership carefully when you combine sub-attributes on a complex collection, since the result can be broader than it first appears.