Build on it. Don't rebuild it.
Sumeru exposes a public REST API, HMAC-signed outbound webhooks, an OpenAPI 3.1 spec, and a cookbook of integration recipes. Your data team integrates with us the same way they'd integrate with Stripe or Twilio — predictable contracts, idempotency keys, documented retry semantics, framework-agnostic event ingest.
Predictable contracts. Documented every way.
Three commands to first event.
Get an API key, fire an event, subscribe to an outbound webhook. Full quickstart with verified curl examples in the docs.
# 1. Get your API key from /app/developers
export SUMERU_KEY="sk_live_..."
# 2. Fire an event
curl -X POST https://api.sumeru.systems/v1/events \
-H "Authorization: Bearer $SUMERU_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"type": "order.created",
"shop": "acme.myshopify.com",
"data": {
"id": "5547283827",
"total_price": "147.00",
"customer_id": 7724108
}
}'
# 3. Subscribe to outbound events (in your app)
# POST /v1/webhooks · subscribe to "attribution.closed"
# Receive HMAC-SHA256-signed payloads at your endpoint.Every contract is explicit.
- Idempotency-Key required on every mutation. Same key + same payload = same result, exactly once.
- Scope-minimised API keys — read-only, write-events-only, full-shop, agency-scoped.
- Per-shop rate limits with X-RateLimit-* headers on every response.
- Versioned — v1 is stable; breaking changes get a v2 with 12-month parallel support.
What you can build on.
Each surface links to its docs section. Full developer docs at sumeru.systems/docs.
Public REST API
v1 · stablev1 stable. OAuth + per-shop API keys with scope minimisation. POST events, GET attribution rollups, manage subscriptions. OpenAPI 3.1 spec for any-language client generation.
Outbound webhooks
HMAC-signedSubscribe to any of the 22 typed events. HMAC-SHA256-signed payloads. Exponential backoff retry × 4, dead-letter queue after. Replay endpoint for missed events.
Event catalog
22 eventsEvery typed event the runtime emits: payload schema, fire conditions, subscribers. The same catalog the dispatcher reads internally — no surprise events.
Cookbook
growingRecipe-style guides for the integrations developers actually build: custom attribution surfaces, ERP sync, identity federation, storefront-widget embed.
Pixel + server-side ingest
framework-agnosticStorefront pixel for D2C; server-side ingest for headless. Identity resolution via Shopify customer ID — no pixel required for Hydrogen / Next / Remix setups.
Rate limits + idempotency
documentedToken-bucket throttle per shop and per platform. Idempotency-Key header on every mutation. Retry semantics + back-off documented per endpoint class.
In your language.
Idiomatic SDKs for Node + Python; raw curl works in any language. Auto-generate clients from the OpenAPI spec for Go, Ruby, PHP, .NET.
import { Sumeru } from "@sumeru/sdk";
const sumeru = new Sumeru({ apiKey: process.env.SUMERU_KEY });
await sumeru.events.create({
type: "order.created",
shop: "acme.myshopify.com",
data: { id: "5547283827", total_price: "147.00" },
}, { idempotencyKey: crypto.randomUUID() });from sumeru import Client
import os, uuid
client = Client(api_key=os.environ["SUMERU_KEY"])
client.events.create(
type="order.created",
shop="acme.myshopify.com",
data={"id": "5547283827", "total_price": "147.00"},
idempotency_key=str(uuid.uuid4()),
)curl -X POST https://api.sumeru.systems/v1/events \
-H "Authorization: Bearer $SUMERU_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"type":"order.created","shop":"acme.myshopify.com","data":{...}}'Node + Python SDKs are first-party · OpenAPI client generators verified for Go, Ruby, PHP, .NET. API reference →
22 typed events. Documented payload, fire conditions, subscribers.
12 shown below; full catalog in the docs. Subscribe to any via outbound webhooks.
| Event type | Category | Fires when |
|---|---|---|
| order.created | sales | Shopify order completed |
| order.refunded | sales | Partial or full refund issued |
| cart.abandoned | sales | Cart inactive past configurable threshold |
| attribution.closed | attribution | Multi-touch attribution finalized for an order |
| decay.detected | seo | Content decay flagged on a tracked page |
| ai-overview.gained | seo | AI Overview cited your page on a tracked query |
| ai-overview.lost | seo | Your page no longer cited in AI Overview |
| ads.roas-dropped | ads | Sustained ROAS decline past threshold |
| mc.disapproval | merchant | Product flagged in Google Merchant Center |
| automation.fired | automation | Rule matched and action dispatched |
| automation.undone | automation | Action reversed via undoHandler |
| audit.logged | compliance | Plain-language audit row written |
What you can depend on.
Semver · 12-month parallel
Breaking changes get a new major version. v1 stays supported for 12 months after v2 ships. Patch + minor changes never break clients.
90-day notice · always
Endpoints marked deprecated 90 days before removal. Deprecation headers on every response. Subscribed customers get email + changelog post.
Typed · documented
Every error response has a typed code, human-readable message, request_id for support, and a docs link. No "internal_error" black box.
Live · subscribable
API health published at /status. Incident webhook subscriptions available for enterprise tier.
Full docs at sumeru.systems/docs.
Quickstart, API reference, webhook signing, event catalog, cookbook recipes, identity integration, architecture deep-dives. Open in a new tab and start building.