Enrichment overview

PartnerConsole already pulls installs, churn, MRR and payouts from the Shopify Partner API on its own, no code. Enrichment is how you add the things the Partner API can't see: everything only your app knows about a merchant.

The two things you can send

Pick either, both, or neither. They're independent, and each one is optional.

1. Identity and custom fields

Who the shop is (name, contact email) plus any attributes you track (plan, seat count, onboarding state, anything). You send these with one call, /identify. They land on the customer record as typed custom fields that are instantly usable in segments, flows, and the customer page.

2. Staff and contacts

The actual people at the merchant, the account owner and staff users. The Partner API never gives you these, so you push them with /staff and they appear as contacts on the customer.

It works for any Shopify app

Enrichment is plain server-to-server JSON authenticated by your app's API key. Embedded or non-embedded doesn't matter to us, your backend obtains what it needs from Shopify and forwards it. (Embedded apps get the current staff member from an App Bridge id_token via token-exchange; non-embedded apps get associated_user from the online OAuth grant. Either way, you send us the result.) There's no SDK and nothing to install in the storefront.

Where custom fields land: your app vs. the workspace

This trips people up, so it's worth being explicit. When you push a custom field, we resolve the name in this order:

1. A field your app already owns (app-scoped) → the value is stored on your app.
2. A shared workspace field the team defined (all-apps or Customers scope) → the value maps there.
3. Nothing matches → we mint a new app-scoped field owned by your app, typed from the first value.

So by default your pushes create and fill your app's own fields, they never collide with another app's field of the same name. A workspace admin can promote a field to the shared Customers scope in the console, and from then on your pushes flow into that shared field. You don't change your code, the resolution just picks the shared field once it exists. See Custom fields for the details.

Quickstart

Grab your app's API key (console → Settings → Integrations → Shopify Partners, one key per tracked app) and identify a customer:

curl -X POST https://api.partnerconsole.co/v1/identify \
  -H "X-Api-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "myshopifyDomain": "example.myshopify.com",
    "name": "Example Store",
    "email": "[email protected]",
    "customFields": {"onboarded": true, "plan_seats": 5}
  }'

That's it, the customer record fills in and the fields become segmentable and flow-usable immediately.

Then, if you track people, forward staff as you see them:

curl -X POST https://api.partnerconsole.co/v1/staff \
  -H "X-Api-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "myshopifyDomain": "example.myshopify.com",
    "staff": [{
      "id": "gid://shopify/StaffMember/123",
      "firstName": "Ada", "lastName": "Lovelace",
      "email": "[email protected]", "accountOwner": true
    }]
  }'

Real-world examples

A few concrete ways apps combine these pieces. Most apps use a mix, and only the parts they need.

A subscription app scoring merchants for an upsell. On install and on every plan change, it pushes plan_tier, seat_count, and monthly_active_users as custom fields. A workspace admin then builds a segment (cf:seat_count gte 10 and cf:plan_tier = "starter") and a flow that emails those merchants an upgrade offer. No staff data needed, just custom fields.

A B2B app reaching the real decision-maker. On install it only has the account owner, so it pushes that person to /staff. When a different staff member later opens the app and finishes onboarding, the app captures them from the token exchange and pushes them too, tagged installer. Now campaigns can target the person who actually configured the app, not just whoever owns the Shopify account.

A sync app surfacing onboarding drop-off. It pushes a boolean has_completed_setup and a last_sync_at custom field, and mirrors its own staff roster nightly with reconcile: true so departed users disappear. Support opens any customer and sees, in one place, who the people are and whether setup ever finished.

Where to go next

Read the guide for the capability you want, then reach for the API reference when you need the exact request and response shape.

• Identify customers — send identity and custom fields.
• Custom fields — scoping, types, unset, read-back.
• Staff & contacts — sync the people, owning the data yourself or letting us hold it.
• Security & safeguards — read this before you ship.
• Set up with AI — hand your AI assistant a ready-made brief.