Set up enrichment with AI
Hand your AI coding assistant a ready-made brief to wire up identify, custom fields, and staff.
Using Cursor, Claude Code, Copilot, or any AI assistant? Paste the brief below into it. It carries the enrichment endpoints, the rules, and the safeguards, so your assistant can implement the integration in one pass. Fill in the two blanks (your stack and which pieces you want) first.
This brief covers enrichment only: identity, custom fields, and staff. Tracking what merchants do in your app is a separate feature with its own AI brief.
The brief
You are integrating my Shopify app with the PartnerConsole enrichment API.
CONTEXT
- My app stack: <e.g. Django + Celery, or Node/Express, or Rails>.
- I want to send: <pick any: custom fields, staff/contacts>.
- Base URL: https://api.partnerconsole.co/v1
- Auth: header `X-Api-Key: <APP_KEY>`. The key is per-app and identifies the app.
It is SERVER-SIDE ONLY. Never expose it to the browser or App Bridge.
REFERENCE DOCS (read these)
- Overview: /developers/guides/enrichment/
- Identify: /developers/guides/identify/
- Custom fields: /developers/guides/custom-fields/
- Staff/contacts: /developers/guides/staff/
- Security: /developers/getting-started/security/
- Request/response schemas: /developers/reference/identify/,
/reference/customer/, /reference/staff/
ENDPOINTS
- POST /identify { myshopifyDomain, name?, email?, customFields? } -> upsert shop + fields
- GET /customer?myshopifyDomain=... -> read shop + fields
- POST /staff { myshopifyDomain, staff:[{id, firstName, lastName, email, accountOwner?, installer?, tags?}], reconcile? }
IMPLEMENTATION RULES
1. Call /identify on install and whenever the merchant's details or a tracked field change. It is idempotent.
2. For staff: obtain `associated_user` from Shopify's token exchange (embedded: exchange the
App Bridge id_token for an ONLINE access token; non-embedded: request an ONLINE token in OAuth).
Forward each user to POST /staff, keyed on `associated_user.id`. Embedded vs non-embedded does not
change our API, only how you get the user from Shopify.
3. Make every call from server-side background work (a queue/worker), never block the request.
4. Handle 429 with exponential backoff. Treat 4xx as permanent (log, don't retry).
5. Store the API key in a secret/env var. Do not log it. Do not send it to the client.
6. Add a Shopify `customers/redact` / `shop/redact` handler that deletes that shop's contacts and
PII custom fields (unset by sending the field as null, or delete via the console).
SAFEGUARDS TO RESPECT
- Custom field TYPE is fixed on first write; always send a value the right shape (number as number,
boolean as boolean). Don't send "5" for a numeric field.
- There are caps on fields-per-call and auto-created definitions; the /identify response returns how
many were written, log it and don't rely on unbounded fields.
- Only send data you have a lawful basis to store; mark sensitive fields private in the console.
DELIVERABLES
- A small server-side client for the endpoints with retry/backoff.
- Wiring: identify on install + on change; staff on session/OAuth.
- The redact webhook handler.
- A short README note on where the API key env var lives.Why a brief and not an SDK
The API is plain JSON over HTTPS, so an AI assistant writes a correct client faster than you'd install and learn an SDK. The brief above is deliberately explicit about the rules and safeguards (key handling, backoff, redaction, type safety) because those are the parts an assistant would otherwise skip. Keep it in your repo (e.g. docs/partner-console.md) so future changes stay consistent.