Skip to main content

Developer documentation

Pick your starting point​

Server-to-server integration

Programmatic access to customers, orders, campaigns, journeys, attribution. Bearer-token authenticated.

Storefront integration

CORS-allowed APIs for reviews, referrals, bundles, upsells, quizzes. No auth required for default storefront use.

Receive Sumeru events

Subscribe Zapier or any HTTPS endpoint — HMAC-signed, retry policy, auto-disable.

Track shopper engagement

First-party JS pixel for browse, cart, custom events. Feeds Customer 360 + attribution.

Worked examples

ERP sync, custom attribution pipeline, embedded storefront widgets — copy-paste-ready code.

The 5 integration surfaces​

v1 admin API

Stable, versioned. Bearer token auth with per-operation scopes.

Public endpoints

Storefront-facing. CORS-enabled or pk_* API key.

Webhooks

Inbound (Shopify, WhatsApp, marketplaces) + outbound (Zapier, custom). HMAC verified both ways.

Storefront pixel

First-party JS SDK for browse / engagement / identity events.

Cookbook

Worked examples for the most common integrations.

Authentication at a glance​

SurfaceAuth methodUse when
Admin APIBearer token (copt_...) — scope-gatedServer-to-server programmatic access
Public endpointsNone (CORS allow-list) or API key (pk_...)Storefront fetches
Webhooks (inbound to Sumeru)HMAC SHA-256 signatureShopify / WA / marketplace deliveries
Webhooks (outbound from Sumeru)HMAC SHA-256 signature your endpoint validatesNotifying your systems

Full details in Authentication & scopes.

Conventions every surface follows​

Error model​

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests; retry after 60s",
    "details": { "retry_after": 60 }
  }
}

Standard codes: unauthenticated, forbidden, not_found, validation_failed, rate_limited, internal_error.

Rate-limit headers​

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 421
X-RateLimit-Reset: 1715346000

Full table in Rate limits.

Idempotency​

All POST and PATCH endpoints support an Idempotency-Key header. Same key + same body in a 24-hour window returns the same response — safe to retry.

Versioning + stability​

The v1 admin API is the stable, semver-versioned surface. Breaking changes get a major bump (v2) with a 12-month deprecation window on the prior version.

Where to go next​

Building...Start here
Server-to-server admin integrationv1 admin API
Storefront integration (reviews, bundles)Public endpoints
Receiving Shopify orders into your systemOutbound webhooks
Tracking shopper engagementPixel integration
Specific worked exampleCookbook

Get help​