Custom fields

Custom fields are the key-value layer on a customer. Your app writes them; the console makes them segmentable, usable in flows, and visible on the customer page. Write and unset through identify; read through customer.

Write

Send customFields on identify. Unknown names create definitions automatically, typed from the first value:

{
  "myshopifyDomain": "example.myshopify.com",
  "customFields": {
    "plan_seats": 5,
    "onboarded": true,
    "sync_settings": {"interval": "daily"}
  }
}

Type inference: number → number, true/false → boolean, object/array → JSON, anything else → text.

Writes are upserts, scoped to your app's installation. Send the full set or a single changed key.

App fields vs. customer fields

A field you push can live in two places, and we pick automatically:

• App fields — owned by your app. This is the default: a name you push that nobody has defined becomes a new app-scoped field on your app. Two apps can push a plan field and they stay separate.
• Customer (workspace) fields — shared across the workspace's apps, defined by the team in the console.

On every write we resolve the name in this order: your app's own field → a shared all-apps field → a Customers-scope field. Only if none exists do we create a new app field. So:

• You always write to your app's field unless a shared field with that exact name already exists.
• A workspace admin can define (or promote) a field to the Customers scope; from then on your existing pushes land in that shared field, no code change on your side.

If you want a field to be shared from day one, have the workspace define it under Customers → Custom fields before you start pushing; otherwise it's yours alone.

Unset

null removes the value; the definition remains:

{"customFields": {"plan_seats": null}}

Read

GET /customer returns every set field with its type:

curl -H "X-Api-Key: $API_KEY" \
  "https://api.partnerconsole.co/v1/customer?myshopifyDomain=example.myshopify.com"

The response includes fields your app didn't write: workspace-scope fields set in the console, defaults standing in for unset fields, and database-linked fields computed from a connected Postgres. Fields marked private in the console are withheld.

Constraints

• Database-linked fields reject pushes. Their SQL query is the source of truth; identify writes to them are skipped silently.
• Type is fixed by the first value. A wrong-shaped first push ("5" instead of 5) locks the type to text; delete the definition in the console before values accumulate, or pre-create it with the right type under Customers › Custom fields.
• Scope resolution on write: your app's own field wins over an all-apps field, which wins over a Customers-scope field of the same name. A new definition is only created when none match.