Skip to main content
This guide is for backend developers building a direct integration against the Stell API. Your systems call the API and own the sync between your customer records and Stell. Four flows make up every integration: Add to Wallet, updating passes, in-store usage, and webhooks and go-live. Where this guide says “your CRM”, read it as whatever system of record you run: a CRM, a loyalty engine, or your own platform. Nothing in the API is specific to any of them.
Stell has prebuilt connectors for a growing set of POS and CRM platforms. If yours is one of them, you may not need to write integration code at all. The connector handles the flows in this guide. Contact us to check what’s available for your stack.

​
Who builds what

The dividing line is simple: you own the calls, Stell owns the wallets.

Stell provides

  • The pass engine: issuance, signing, and distribution for Apple Wallet and Google Wallet
  • Real-time pass updates and push notifications to customer devices
  • A permanent Add to Wallet link on every pass, with a hosted pass page or direct wallet delivery
  • Signed webhooks that tell your backend when a pass changes status
  • The merchant portal, for self-service management of your pass templates and change messages

You build

  • A server-side service that calls the Stell API
  • An Add to Wallet touchpoint: a page, app screen, or email
  • An HTTPS webhook endpoint that receives status events
  • The mapping between your customer records and passes, via externalId
  • The business logic: when points change, when tiers change, what messages to send

​
Before you start

You need three things:
  1. An API key for your backend (Authorization: Bearer sk_prod_…). Create one in the portal. It must stay server-side; see Authentication.
  2. Your programId, the identifier for your pass program, used in every create and lookup call. Find it with List programs or in the portal.
  3. A webhook subscription: your endpoint URL, the event types you want, and a signing secret, created in the portal.

​
Core concepts

externalId. Your own customer identifier, and the join key across the whole integration. You set it at pass creation, use it for lookups, and get it back in every webhook delivery. No extra mapping table needed. Pass id. Stell’s identifier for a pass, returned when the pass is issued. Store it on your customer record: it is what keeps the integration to one pass per customer, since the API creates a new pass on every create call. If you don’t store it, look it up by programId + externalId before every create. See Add to Wallet. Pass link. Every pass response carries a permanent public link. It never expires, so store it, email it, or print it as a QR code. Opened as-is it shows a hosted page with the right wallet button; with ?delivery=direct it redirects straight to the wallet artifact. Only the optional walletLink (via includeWalletLink=true) and the deprecated per-wallet link endpoints are short-lived — roughly 15 minutes for Apple Wallet, roughly an hour for Google Wallet — and those you request at the moment of use. See Add to Wallet. Wallet-controlled display. Apple and Google decide the final presentation of passes and notifications, and may coalesce rapid updates. Don’t design flows that rely on one visible notification per update. The in-store payload. What your POS reads from a scan or tap is a choice, not a constant. Set it with the payload field when issuing the pass, or configure it on the pass template with placeholders such as {{externalId}}. Left unset, it falls back to the pass id. See In-store.

​
Endpoint summary

The complete surface a typical integration touches: Inbound to you: webhook deliveries, signed POSTs to your endpoint when a pass changes status or a transaction is recorded.