Events API
POST /v1/events: send usage events from your app.
Send up to 100 usage events in one request. Valid events are stored even when others in the same request are rejected.
Request
POST https://www.apps-patrol.com/v1/events
Authorization: Bearer <ingest key>
Content-Type: application/json
{
"events": [
{
"event_id": "0b7f0c1e-6d0a-4d6f-9a56-3f1c8f1f2a10",
"shop": "example.myshopify.com",
"name": "feature_used",
"occurred_at": "2026-11-17T09:30:00Z",
"properties": { "feature": "bulk_edit", "items": 42 }
}
]
}
Event fields
| Field | Required | Rules |
|---|---|---|
event_id | Yes | Your unique ID for the event, a string of at most 200 characters (a UUID works well). The same ID sent again for the same app is counted as a duplicate and not stored twice. |
shop | Yes | The shop's *.myshopify.com domain. A shop that is not known yet is created. |
name | Yes | At most 100 characters from a-z, 0-9, _, ., : and -, for example feature_used or checkout.step:2. |
occurred_at | No | ISO 8601 time, not more than 7 days in the past or 1 hour in the future. Defaults to the time of receipt. |
properties | No | A JSON object: at most 50 top-level keys, 3 levels of nesting and 8 KB. |
Responses
| Status | Meaning |
|---|---|
202 | At least one event was stored or recognised as a duplicate. Check errors for rejected events. |
422 | Nothing could be stored: every event was invalid (invalid_request, with errors), events is not an array (invalid_request), or there are more than 100 events (batch_too_large). |
401 | unauthorized: missing, wrong or rotated ingest key. |
413 | payload_too_large: the body is over 512 KB. |
429 | rate_limited (too many requests this minute) or quota_exceeded (monthly allowance used). |
202 body
{
"accepted": 1,
"duplicates": 0,
"errors": [
{ "index": 1, "code": "missing_shop", "message": "shop is required" }
]
}
| Field | Meaning |
|---|---|
accepted | Events newly stored. |
duplicates | Valid events whose event_id was already stored for this app, or repeated within the request. |
errors | Rejected events. index is the position in your events array; code is one of the per-event codes. |
422 body when every event is invalid
{
"error": { "code": "invalid_request", "message": "No event in the request could be stored", "docs": "https://www.apps-patrol.com/docs/errors#invalid_request" },
"accepted": 0,
"duplicates": 0,
"errors": [
{ "index": 0, "code": "missing_event_id", "message": "event_id is required" }
]
}
Limits
| Limit | Value |
|---|---|
| Events per request | 100 |
| Request body | 512 KB |
| Requests per ingest key | 600 per minute, shared by all /v1 endpoints |
| Events per organization per month | Free 10,000 · Solo 250,000 · Studio 2,000,000 · Agency 10,000,000 |
Rate limit headers
Every response carries the state of the per-minute limit:
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597
X-RateLimit-Reset: 1794907260
X-RateLimit-Reset is the Unix time when the window ends. A 429 rate_limited response also has Retry-After in seconds.
Monthly quota
Only newly stored events count; duplicates and rejected events do not. The month is a calendar month in UTC. When the allowance is used, requests are answered with 429 quota_exceeded and nothing is stored until the next month or a plan change. The Events page shows the current usage, ping returns it, and the “Event quota” alert warns you at 80% and 100%.
Behaviour to rely on
- Idempotent: retry a failed request with the same
event_ids. Nothing is stored or counted twice. - Order does not matter: events are placed by
occurred_at. - Partial success: one bad event does not reject the batch.
Test mode
Add the header X-Apps-Patrol-Test: true to validate a request without storing anything. The response is the one you would get, plus "test": true. Test requests do not count toward the monthly quota; they do count toward the rate limit.
Example
curl -X POST https://www.apps-patrol.com/v1/events \
-H "Authorization: Bearer $APPS_PATROL_KEY" \
-H "Content-Type: application/json" \
-d '{"events":[
{"event_id":"evt-1001","shop":"example.myshopify.com","name":"app_opened"},
{"event_id":"evt-1002","shop":"example.myshopify.com","name":"feature_used","properties":{"feature":"bulk_edit"}}
]}'
{"accepted":2,"duplicates":0,"errors":[]}