Skip to main content
skill CX Codex

revenuecat-audiences — Claude Code skill: filters, install

The revenuecat-audiences skill guides RevenueCat customer filtering and ranking, reads segment statistics, and returns a dashboard view for the selected audience.

MIT 313 installs ★ 79 updated 2026-10-21

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add RevenueCat/ai-toolkit --skill revenuecat-audiences -a claude-code
Open on GitHub

What revenuecat-audiences does

revenuecat-audiences gives an agent a workflow for RevenueCat Audiences. It can map requests to product, subscription state, country, platform, spend, renewals, attribution, dates, email, app user ID, or custom attributes.

The workflow fetches project-level values with get-audience-filter-options, then previews a segment through preview-audience. A saved audience can be passed with audience_uuid; ranking uses sort_by and sort_direction. Counts come from stats, while customer names must come from customer_sample. A project_id is required for these calls.

The result provides a dashboard view URL. An ad-hoc filter is not saved; persistence requires create-audience. Saved links use customer_list_id, which is different from the audience id.

What it helps with

  • filter customers by product, status, or country
  • find users above a spend or renewal threshold
  • rank customers by total_spent
  • read customer and subscription counts from a segment
  • share a dashboard view for a filtered audience

Example prompts for the agent

  • Find Android customers with an active subscription and share the matching dashboard view.
  • Show the highest-spending customers by total_spent, using names returned in customer_sample.
  • How many customers and active trials are in this product segment? Read the answer from stats.

How to install revenuecat-audiences

1Skills CLI (Vercel)

npx skills add RevenueCat/ai-toolkit --skill revenuecat-audiences -a claude-code

2Manually: put the files in place

~/.claude/skills/revenuecat-audiences/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/revenuecat-audiences/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about revenuecat-audiences

How do I install revenuecat-audiences in Claude Code?

Run npx skills add RevenueCat/ai-toolkit --skill revenuecat-audiences -a claude-code, then check ~/.claude/skills/revenuecat-audiences/SKILL.md.

What does revenuecat-audiences do?

It gives the agent a procedure for filtering, sorting, and counting RevenueCat customers, then sharing the matching dashboard view.

How does it count customers and identify top spenders?

Counts come from stats. Top spenders use sort_by: total_spent with sort_direction: desc, while names come only from the returned customer_sample.

Source text

SKILL.md · MIT
---
name: revenuecat-audiences
description: >
  Use before sharing a link to a filtered customer list or audience, and when identifying,
  filtering, or ranking the user's customers (a segment, who they are, a product or duration,
  spend, renewals, status, country, attribution).
---

# Audience filters and dashboard links

Use Audiences to filter the user's customers and to share a dashboard link to that set. Filters
select the segment; `sort_by` / `sort_direction` on `preview-audience` order the returned sample.

There is no first-class CLI command for audiences. Do not tell the user RevenueCat cannot filter
or segment customers.

## Identifying, filtering, or ranking customers

Audiences filter on the [fields](#fields) below, including:

- Product and duration — `latestProduct`, `allPurchasedProductIds`, `latestPurchasedOffering`,
  entitlements, offers
- Spend and renewals — `totalSpent` (filter, and `sort_by: total_spent`), `totalRenewals` (filter
  only; there is no renewal sort)
- Subscription state — `status`, trial, auto-renew intent, ownership
- Store, platform, and country — `platform`, `latestStore`, `country`, `storefront`
- Dates — first seen, purchases, renewals, expiration, trial, cancellation
- Attribution and experiments — media source, campaign, ad group, keywords, price experiment
- Identity and custom attributes — app user ID, email, locale, `customAttribute:{key}`

Map the question onto those fields, filter, then read a sample.

1. Fetch project-specific values with `get-audience-filter-options` for any field marked
   project-specific that the question uses (`project_id`, `fields`).
2. Call `preview-audience` with `project_id` and `body.rules` in the [filter rule](#the-filter-rule)
   shape (for a saved audience from `list-audiences`, pass `body.audience_uuid` instead). It is
   read-only and saves nothing. Do not `create-audience` just to inspect a segment.
3. To rank or name a superlative, pass `sort_by` (`status`, `latest_auto_renew_intent`,
   `first_seen_at`, `last_seen_at`, `total_spent`) and `sort_direction` (`asc` default, or `desc`)
   as top-level parameters, not inside `body`. `sort_by: total_spent` with `sort_direction: desc`
   returns the highest spenders first, so the first `customer_sample` row is the top spender. The
   sample is capped (typically 50): it is the top or bottom matches, not every customer.
4. Answer "how many" from `stats` (`total_customers`, `active_subscriptions`, `active_trials`,
   `total_revenue` in `currency`), never from the sample size. When `stats.is_approximate` is true,
   give counts and revenue as approximate ("about 6,400 customers").
5. Name customers only from fields `customer_sample` returned (`app_user_id`, `email`, `status`,
   `total_spent`, `latest_product_name`, first/last seen). Without `sort_by` the sample is
   unordered: say it is a sample of matches, not a ranking.
6. `totalRenewals` is a filter only, not a `sort_by` value or a sample column. Filter on a high
   threshold and report the matches; do not invent a renewal count or claim a unique maximum.
7. Share the dashboard link. The `preview-audience` result for `body.rules` includes a line
   starting "Dashboard URL for this result"; link that exact URL. Build one yourself
   ([constructing a link](#constructing-a-link)) only when no tool result gave you a URL.

## Constructing a link

Use this only when no tool result gave you a "Dashboard URL for this result" line. Two shapes: a
filtered `all-customers` link for ad-hoc exploration, and a saved-audience link after
`create-audience`.

1. Get the project ID from `list-projects`. For dashboard URLs, **strip the `proj` prefix**.
2. Pick fields and operators from the [field tables](#fields). Do not invent field or operator
   names.
3. For project-specific fields, fetch valid values with `get-audience-filter-options` first.
4. Assemble the [rule JSON](#the-filter-rule): one group per OR-branch, conditions inside a group
   for AND, values encoded per [value formats](#value-formats).
5. Serialize and URL-encode the rule with a short script (see [encoding the rule](#encoding-the-rule))
   — do not encode by hand.
6. Append it as the `filters` query param on
   `https://app.revenuecat.com/projects/{project_id}/customer-lists/all-customers`.

## URL format

```
https://app.revenuecat.com/projects/{project_id}/customer-lists/all-customers?filters={encoded_rule}
```

- `{project_id}` — short hex ID from `list-projects` with `proj` stripped.
- Filters only work on the `all-customers` list. The unfiltered Audiences home is
  `/projects/{project_id}/customer-lists`.

## Linking to a saved audience

The `create-audience` and `get-audience` results include a "Dashboard URL for this result" line;
link that exact URL. If you only have `list-audiences` output, link with `customer_list_id`, the
field returned alongside `id`:

```
https://app.revenuecat.com/projects/{project_id}/customer-lists/{customer_list_id}
```

**An audience's `id` (`aud…`) and its `customer_list_id` (`list…`) are different identifiers.**
The dashboard route only resolves `customer_list_id`; an `aud…` id in that slot renders
"Audience not found".

**Correct:**

```
https://app.revenuecat.com/projects/56965ae1/customer-lists/list7c1f0a2b93
```

**Wrong** (the audience `id` instead of the `customer_list_id`):

```
https://app.revenuecat.com/projects/56965ae1/customer-lists/audf0269cdf3df84dd2
```

Do not add a `filters` param to a saved-audience link — the audience carries its own rules. If
the response has no `customer_list_id`, link to `/customer-lists` and name the audience rather
than guessing an id.

## Offering to save the filtered view

A filtered `all-customers` link is ad-hoc — nothing about it is saved. Say so in one short
sentence when you share one, and offer to save it: "This view isn't saved — want me to save it
as an audience so you can find it later?"

Offer once per conversation. If they accept, call `create-audience` with the same rule you built
for the link, then link to it. Do not offer when the link is already to a saved audience.

## The filter rule

The `filters` value is URL-encoded JSON with this shape:

```json
{
  "groups": [
    {
      "conditions": [{ "field": "platform", "operator": "is", "value": "android" }]
    }
  ]
}
```

- Conditions within a group combine with AND.
- Groups combine with OR.
- `value` is always a JSON string — booleans as `"true"`/`"false"`, numbers as `"42"`, lists as a
  comma-separated string, date ranges and relative dates as stringified JSON (see
  [value formats](#value-formats)).

**Correct** (compact JSON, whole value URL-encoded):

```
?filters=%7B%22groups%22%3A%5B%7B%22conditions%22%3A%5B%7B%22field%22%3A%22platform%22%2C%22operator%22%3A%22is%22%2C%22value%22%3A%22android%22%7D%5D%7D%5D%7D
```

**Wrong** (raw JSON, spaces, unencoded quotes/braces):

```
?filters={"groups": [{"conditions": [...]}]}
```

## Encoding the rule

```python
import json
from urllib.parse import quote

rule = {
    "groups": [
        {"conditions": [{"field": "platform", "operator": "is", "value": "android"}]},
    ]
}

print(quote(json.dumps(rule, separators=(",", ":")), safe=""))
```

## Fields

The Audiences preview table shows only **Customer**, **Subscription Status**,
**Auto-Renewal Status**, **Spent**, and **Latest Purchase**. Other attributes appear in the CSV
from **Export all**, or on a customer's profile.

Use these exact `field` strings. See
[Audiences](https://www.revenuecat.com/docs/dashboard-and-metrics/audiences).

### Text fields

Operators: `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`.

| Field                     | Meaning                           |
| ------------------------- | --------------------------------- |
| `customerId`              | App user ID                       |
| `originalAppUserId`       | Original app user ID              |
| `email`                   | Email                             |
| `phoneNumber`             | Phone number                      |
| `locale`                  | Locale                            |
| `appVersion`              | App version                       |
| `sdkVersion`              | SDK version                       |
| `platformVersion`         | Platform (OS) version             |
| `projectId`               | Project ID (e.g. `proj1ab2c3d4`)  |
| `projectName`             | Project name                      |
| `appConfigId`             | App ID (e.g. `app1ab2c3d4`)       |
| `appConfigName`           | App name                          |
| `idfa`                    | IDFA                              |
| `idfv`                    | IDFV                              |
| `gpsAdId`                 | GPS ad ID                         |
| `latestPurchasedOffering` | Latest purchased offering         |
| `latestOffer`             | Latest offer identifier           |
| `latestEntitlements`      | Latest entitlement identifiers    |
| `allPurchasedProductIds`  | All purchased product identifiers |

### Enum fields

Operators: `is`, `isNot`, `isAnyOf`, `isNotAnyOf`, `isEmpty`, `isNotEmpty`.

| Field                    | Values                                                                                                                    |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `platform`               | `iOS`, `android`, `web`, `macOS`, `amazon`, `roku`, `tvOS`, `visionOS`, `watchOS`                                         |
| `status`                 | `active`, `trialing`, `in_grace_period`, `in_billing_retry`, `paused`, `expired`, `incomplete`, `unknown`                 |
| `latestStore`            | `app_store`, `play_store`, `promotional`, `mac_app_store`, `stripe`, `amazon`, `roku`, `rc_billing`, `paddle`, `external` |
| `anyActiveStore`         | Any active store — same store identifiers as `latestStore`                                                                |
| `latestOwnershipType`    | `PURCHASED`, `FAMILY_SHARED`                                                                                              |
| `latestOfferType`        | `no_offer`, `free_trial`, `introductory_offer`, `offer_code`, `promotional_offer`, `win_back_offer`, `unspecified_offer`  |
| `priceExperimentVariant` | `a`, `b`, `c`, `d`                                                                                                        |
| `country`                | Last seen country — ISO 3166-1 alpha-2 codes (e.g. `US`, `DE`)                                                            |
| `latestStoreCountry`     | ISO 3166-1 alpha-2 country codes                                                                                          |
| `storefront`             | Store country — ISO 3166-1 alpha-2 codes                                                                                  |
| `mediaSource`            | project-specific — [fetch valid values](#fetching-project-specific-values)                                                |
| `campaign`               | project-specific                                                                                                          |
| `adGroup`                | project-specific                                                                                                          |
| `ad`                     | project-specific                                                                                                          |
| `keyword`                | project-specific                                                                                                          |
| `creative`               | project-specific                                                                                                          |
| `priceExperimentId`      | project-specific                                                                                                          |
| `latestProduct`          | product IDs of the project — fetch valid values                                                                           |

### Boolean fields

Operators: `is`, `isNot`. Value is exactly `"true"` or `"false"`.

| Field                            | Meaning                                              |
| -------------------------------- | ---------------------------------------------------- |
| `hasMadeSandboxPurchase`         | Has made a sandbox purchase                          |
| `hasMadeNonSubscriptionPurchase` | Has made a non-subscription purchase                 |
| `latestAutoRenewIntent`          | Auto-renewal status (`true` = set to renew)          |
| `isCurrentlyTrialing`            | Currently trialing                                   |
| `isRcPromo`                      | Has been granted an entitlement via RC (promotional) |

### Number fields

Operators: `equal`, `notEqual`, `greaterThan`, `greaterThanOrEqual`, `lessThan`,
`lessThanOrEqual`, `isEmpty`, `isNotEmpty`. Value is a numeric string, e.g. `"50"`.

| Field           | Meaning                  |
| --------------- | ------------------------ |
| `totalSpent`    | Total spent              |
| `totalRenewals` | Total number of renewals |

### Date fields

Operators: `before`, `beforeOrOn`, `on`, `after`, `afterOrOn`, `within`, `between`, `notBetween`,
`isEmpty`, `isNotEmpty`.

| Field                  | Meaning                        |
| ---------------------- | ------------------------------ |
| `firstSeenAt`          | First seen                     |
| `lastSeenAt`           | Last seen                      |
| `firstPurchaseAt`      | First purchase                 |
| `mostRecentPurchaseAt` | Most recent purchase           |
| `mostRecentRenewalAt`  | Most recent renewal            |
| `latestExpirationAt`   | Latest expiration              |
| `trialStartAt`         | Trial start                    |
| `trialEndAt`           | Trial end                      |
| `subscriptionOptOutAt` | Most recent cancellation       |
| `trialOptOutAt`        | Most recent trial cancellation |

### Custom attribute fields

Filter with `customAttribute:{key}` (e.g. `customAttribute:favorite_team`). They use the enum
operators. Fetch known keys and values with `get-audience-filter-options` — never invent a key.

## Value formats

- `isEmpty` / `isNotEmpty` — set `"value": ""` (the value is ignored).
- `isAnyOf` / `isNotAnyOf` — comma-separated string: `"value": "US,CA,MX"`.
- `before`, `beforeOrOn`, `on`, `after`, `afterOrOn` — calendar date `"value": "2026-01-31"`
  (`YYYY-MM-DD`).
- `between` / `notBetween` — stringified JSON with exactly `from` and `to`:
  `"value": "{\"from\":\"2026-01-01\",\"to\":\"2026-01-31\"}"` (`from` ≤ `to`).
- `within` — stringified JSON with exactly `direction`, `value`, `unit`:
  `"value": "{\"direction\":\"last\",\"value\":30,\"unit\":\"days\"}"`. `direction` is `last` or
  `next`; `unit` is `minutes`, `hours`, or `days`; `value` is a non-negative integer.
  `before`/`beforeOrOn`/`after`/`afterOrOn` also accept this relative format (not `on`).

## Fetching project-specific values

Fields marked project-specific (`mediaSource`, `campaign`, `adGroup`, `ad`, `keyword`, `creative`,
`priceExperimentId`, `latestProduct`) and custom attributes only match values that exist in the
project's data. Fetch with `get-audience-filter-options`:

- `project_id` (required)
- `fields` (required, at least one) — any of the eight fields above, `customAttribute:{key}` for
  one custom attribute, or `customAttribute` to list every custom attribute key with its values.

A custom-attribute entry may come back with `cardinality_exceeded: true` — a value the user
stated verbatim can still be valid even if it is not in the list.

Fixed-value fields (`country`, `platform`, `status`, …) are not served by this tool — use the
tables above. Never guess project-specific values — a filter on a non-existent value silently
matches zero customers.

## Example: building a link

User wants: "Android customers acquired through Instagram" in project `proj56965ae1`.

Rule (both conditions in one group — AND):

```json
{
  "groups": [
    {
      "conditions": [
        { "field": "platform", "operator": "is", "value": "android" },
        { "field": "mediaSource", "operator": "is", "value": "Instagram" }
      ]
    }
  ]
}
```

Link:

```
https://app.revenuecat.com/projects/56965ae1/customer-lists/all-customers?filters=%7B%22groups%22%3A%5B%7B%22conditions%22%3A%5B%7B%22field%22%3A%22platform%22%2C%22operator%22%3A%22is%22%2C%22value%22%3A%22android%22%7D%2C%7B%22field%22%3A%22mediaSource%22%2C%22operator%22%3A%22is%22%2C%22value%22%3A%22Instagram%22%7D%5D%7D%5D%7D
```

User wants: "customers on iOS or Android who are currently trialing and were first seen in the
last 30 days".

```json
{
  "groups": [
    {
      "conditions": [
        { "field": "platform", "operator": "isAnyOf", "value": "iOS,android" },
        { "field": "isCurrentlyTrialing", "operator": "is", "value": "true" },
        {
          "field": "firstSeenAt",
          "operator": "within",
          "value": "{\"direction\":\"last\",\"value\":30,\"unit\":\"days\"}"
        }
      ]
    }
  ]
}
```

© RevenueCat · MIT · RevenueCat/ai-toolkit

Similar skills

All skills for Data and databases →

From the same set45

The whole set →
revenuecat-experiments revenuecat-experiments is a Claude Code skill that prepares and manages RevenueCat A/B tests through MCP tools. It sets up variant offerings and controls the experiment lifecycle. CX Codex +1 449installs revenuecat-paywall-design revenuecat-paywall-design — a skill for creating, editing and auditing RevenueCat paywalls from your code editor. Manages dashboard paywall configuration, uploads media and fonts, generates designs from descriptions. CX Codex +1 351installs revenuecat-dashboard-links This skill teaches the agent to build RevenueCat dashboard links for offerings, products, paywalls and customers. Handy when an answer needs a clickable page instead of a bare ID. CX Codex +1 319installs revenuecat-forecasting revenuecat-forecasting projects MRR, ARR, and subscriber metrics from RevenueCat account data. Models cohort-based churn steps and required acquisition spend for revenue goals. CX Codex +1 316installs revenuecat-billing The revenuecat-billing skill lets an agent inspect a developer’s RevenueCat plan, MTR, invoices, and payment setup. It works with Claude Code, Codex, Cursor, and other listed platforms. CX Codex +1 315installs revenuecat-app-valuation revenuecat-app-valuation works out what a subscription app might be worth and explains how an acquisition usually goes, grounding the estimate in the project's own RevenueCat numbers. CX Codex +1 312installs revenuecat-experiment-analysis revenuecat-experiment-analysis walks a RevenueCat experiment through its steps: find the ID, pull setup, charts and results, then explain what the numbers mean. CX Codex +1 289installs rc rc is a Claude Code plugin for managing RevenueCat projects and in-app purchase settings. It connects to an account through OAuth. ★ 79repo stars

Project sponsors

Companies that keep this analytics open