API Docs
Reference for the Subscription Concierge backend API.
Two authentication models
Almost everything in the API falls into one of two categories, authenticated differently:
| Surface | Auth | Used by |
|---|---|---|
Merchant dashboard endpoints/api/tiers, /api/customers, /api/bundles, /api/upsells, /api/settings, /api/users, /api/analytics, etc. |
Shopify session token — Authorization: Bearer <jwt> |
The merchant dashboard, right after your store's OAuth install completes. |
Customer portal endpoints/api/proxy/portal/* |
Shopify App Proxy signing — an HMAC signature Shopify itself attaches to storefront requests | The customer self-service portal, embedded in your storefront via a theme app extension. There's no separate login for shoppers — Shopify's own signed session identifies them. |
A third small category — the mandatory Shopify compliance webhooks (customers/redact,
customers/data_request, shop/redact) and the billing/order webhooks — are verified
via Shopify's own webhook HMAC signature (X-Shopify-Hmac-Sha256), not either of the above.
Getting a session token (merchants)
You don't request this manually — it's issued automatically as part of the OAuth install flow. Once a merchant installs the app and completes Shopify's consent screen, the dashboard receives a signed session token and attaches it to every subsequent API call automatically.
Outbound webhooks
If you're integrating your own systems with Subscription Concierge (rather than just using the dashboard), you
can register a callback URL to receive event notifications — subscription lifecycle events like
subscription/anchored and queue/shifted. See
the webhook-management endpoints
in the interactive reference for how to register one.
Each delivery is signed: we compute an HMAC-SHA256 signature over the raw JSON body using the secret you were
given when you registered the webhook, and send it as X-SubscriptionConcierge-Signature, alongside
X-SubscriptionConcierge-Event naming which event fired. Verify the signature before trusting a
payload, the same way you'd verify any other webhook provider's.
Rate limits & versioning
The API doesn't currently enforce a published rate limit — during private beta, usage is light enough that this hasn't been a constraint. If that changes as usage grows, limits will be documented here before they're enforced, not after.