Ingest usage events

POST/api/v1/usage_events

Reports what merchants do inside your app. Events power the Behavior section (analytics, funnels, metrics) and can trigger flows.

Send a single event at the root, or a batch of up to 200 under events; a top-level myshopifyDomain covers events without their own customerId. Events named page_view with a path feed web analytics and page-view reports.

Event fields

eventNamestringrequired

Stable, action-shaped name (name is accepted as an alias).

customerIdstringrequired

The shop’s myshopify domain (myshopifyDomain is an alias).

eventIdstring

Idempotency key; duplicates are silently dropped, so retries are safe.

timestampstring

ISO 8601; defaults to arrival time.

propertiesobject

Free-form; numeric values power report calculations.

pathstring

For page_view events.

sessionKeystring

Groups page views into sessions; a 30-minute gap rule applies regardless.

Returns

202Ingested; dropped counts nameless or shopless events.

400No valid events in the payload.

401Bad or missing X-Api-Key.

429Past 1,200 events/minute for this app.

Request

cURL

curl -X POST \
  https://partnerconsole.co/api/v1/usage_events \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eventName": "first_quote_created",
    "customerId": "example.myshopify.com",
    "eventId": "q-1042-created",
    "properties": {"value": 120}
  }'

Node.js

await fetch(
  'https://partnerconsole.co/api/v1/usage_events',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.PC_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      myshopifyDomain: shop.domain,
      events: [
        {
          eventName: 'first_quote_created',
          eventId: `q-${quote.id}-created`,
          properties: {value: quote.total},
        },
        {
          eventName: 'page_view',
          path: '/quotes',
          sessionKey: session.id,
        },
      ],
    }),
  },
);

Python

import os, requests

requests.post(
    "https://partnerconsole.co/api/v1"
    "/usage_events",
    headers={
        "X-Api-Key": os.environ["PC_API_KEY"],
    },
    json={
        "eventName": "first_quote_created",
        "customerId": shop.domain,
        "eventId": f"q-{quote.id}-created",
        "properties": {
            "value": float(quote.total),
        },
    },
    timeout=10,
)

Response · 202

{
  "accepted": 2,
  "dropped": 0
}