Custom fields

Your app knows things about a merchant that no revenue feed ever will: how many seats they use, whether they finished onboarding, the score your team gives the account. Custom fields give that knowledge a home on the customer record, and once it's there, you can see it on every profile, filter by it in segments, and branch on it in flows.

A concrete example: add a "customer score" field, have your app push a score for each shop, and suddenly "our best customers on the cheapest plan" is a segment you can build in ten seconds.

Choosing a scope

Every field applies at one of three levels, and picking the right one keeps your data tidy:

• One app: the value lives on that app's installation. Two apps can each track their own plan_seats without ever colliding. This is the usual choice.
• All apps: the field exists on every app, and each app fills in its own value per shop. Handy when several apps track the same concept, like a health score.
• Customers: one value per shop, independent of apps. Best for things your team assigns, like an account tier.

Choosing a type

Fields come in four types: text, number, boolean, and JSON for anything structured. The type shapes everything downstream: booleans render as a clean Yes/No, numbers unlock "at least" and "at most" conditions in segments, and text supports "contains". Pick the type that matches how you'll filter later.

Three ways values arrive

1. Your app pushes them. Send fields through the identify API and they appear on the customer within seconds. Fields your app sends for the first time create themselves automatically, so there's no setup step to forget. Pushing null clears a value.
2. Your database computes them. Connect a read-only PostgreSQL user under Settings › Integrations, give the field a SQL query, and the console re-runs it on a schedule. Perfect for computed values like 30-day usage that you'd rather not push event by event.
3. A flow sets them. The flow builder's Set custom field action stamps a value when a customer reaches that step, which makes lifecycle milestones queryable forever after.

Fine-tuning a field

Each field carries a few switches that control where it shows up:

• Default value: stands in wherever a shop has no value of its own, so reports and segments never have holes.
• Private field: never returned by the API; visible only to you in the dashboard. Use it for internal notes your apps shouldn't see.
• Show on the customer page: turn off for bookkeeping fields that would clutter profiles.
• Available for filtering: turn off to keep a field out of the segment builder and customer filters.

Managing your fields

Everything lives at Customers › Custom fields: create fields ahead of time to lock in the right type, edit names and options, or delete a definition. Deleting is blocked while values exist, so a typo'd duplicate is easy to remove but real data can't vanish by accident.

And everything your app can write, it can read back: the customer read API returns every set field with its type. Once your fields are flowing, your customer records finally know what your app knows.