Developers

The events feed

Pull-based change consumption: the envelope, cursor paging, type filters, checkpoints, and events vs webhooks.

Pull instead of push

GET /v1/events (scope events:read) serves the same events webhooks push, as an ordered cursor feed — the right choice when your integration can't expose an HTTPS endpoint, or when you want consumption under your own scheduler.

curl -sS "https://api.itemra.io/v1/events?limit=50" \
  -H "Authorization: Bearer $ITEMRA_API_KEY"

The envelope

{
  "id": "evt_01…",
  "type": "stock.changed",
  "version": 1,
  "occurredAt": "2026-07-13T10:15:30Z",
  "organizationId": "org_01…",
  "data": {}
}

Event ids are stable — they're your deduplication keys. Use occurredAt for domain time (never arrival order), and ignore unknown fields so compatible additions don't break you. The catalog matches webhooks: stock.changed, item.created, item.updated, movement.created, po.received, count.completed, low-stock, export.completed.

Cursors and checkpoints

Persist page.nextCursor and send it unchanged as cursor — also when data was empty: a filtered empty page can still advance the cursor past unrelated events. limit defaults to 50 (max 200); a single type filter narrows the feed.

If you'd rather checkpoint on event ids, use type=<event-type>&afterEventId=<last-id> instead of a cursor (never both). An unknown or expired checkpoint returns a validation problem so you reset deliberately instead of silently skipping.

Choosing between events and webhooks

Webhooks give lower latency and no polling cost, but demand a hardened receiver (signatures, idempotency, availability). The feed gives you at-your-own-pace consumption with nothing exposed. Many integrations run both: webhooks for speed, a nightly feed sweep for assurance.