Set up usage events with AI
Hand your AI coding assistant a ready-made brief to report in-app actions and page views.
Using Cursor, Claude Code, Copilot, or any AI assistant? Paste the brief below into it. It carries the usage-events endpoint, the naming rules, and the safeguards, so your assistant can wire up behavior tracking in one pass. Fill in the two blanks (your stack and the key moments you want to instrument) first.
This brief covers usage events only: what merchants do in your app. Sending who the customer is (identity, custom fields, staff) is a separate feature with its own AI brief.
The brief
You are integrating my Shopify app with the PartnerConsole usage-events API.
CONTEXT
- My app stack: <e.g. Django + Celery, or Node/Express, or Rails>.
- Key moments to instrument: <e.g. first_sync, order_synced, report_exported, onboarding steps>.
- Base URL: https://api.partnerconsole.co/v1
- Auth: header `X-Api-Key: <APP_KEY>`. The key is per-app and SERVER-SIDE ONLY.
Never expose it to the browser or App Bridge.
REFERENCE DOCS (read these)
- Track usage events: /developers/guides/usage-events/
- PartnerConsole Pixel (listing analytics): /developers/guides/pixel/
- Security: /developers/getting-started/security/
- Request/response schemas: /developers/reference/usage-events/,
/reference/usage-events-list/, /reference/usage-events-report/
ENDPOINT
- POST /usage_events single: { eventName, customerId, eventId?, timestamp?, properties? }
batch: { myshopifyDomain, events:[ {eventName, eventId?, ...}, ... ] } (up to 200)
- A page view is an event named "page_view" with a "path" (and optional "sessionKey").
IMPLEMENTATION RULES
1. Send from server-side background work (a queue/worker), never block the request.
2. Always set a stable `eventId` per logical event so retries are idempotent (no duplicates).
3. Keep event names stable and action-shaped (report_exported, not ReportPage_Export_Clicked_v2).
Put anything variable in `properties`, not in the name.
4. Instrument the three moments that define activation: first unit of value, the repeat action that
predicts retention, and each onboarding step. Don't fire an event on every click.
5. Handle 429 with exponential backoff. Treat 4xx as permanent (log, don't retry).
6. Store the API key in a secret/env var. Do not log it. Do not send it to the client.
SAFEGUARDS TO RESPECT
- customerId / myshopifyDomain must be the shop's myshopify domain, not an internal id.
- Don't put PII in event names or properties beyond what you have a lawful basis to store.
- Batch high-volume events (up to 200 per call) instead of one request each.
DELIVERABLES
- A small server-side client for /usage_events with retry/backoff and idempotent eventIds.
- Wiring at each instrumented call site (activation moments, key repeat actions, onboarding).
- A short README note on where the API key env var lives and the list of event names you emit.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 is deliberately explicit about the naming discipline and idempotency, because those are the parts an assistant would otherwise skip, and they're what keep your Behavior reports clean. Keep it in your repo so future events stay consistent.