> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getstell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration overview

> The flows, concepts, and endpoints behind a direct API integration

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](/api-reference/integration/add-to-wallet), [updating passes](/api-reference/integration/updating-passes), [in-store usage](/api-reference/integration/in-store), and [webhooks and go-live](/api-reference/integration/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.

<Note>
  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](/support/contact) to
  check what's available for your stack.
</Note>

## Who builds what

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

<Columns cols={2}>
  <Card title="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
    * Short-lived Add to Wallet links for both platforms
    * 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
  </Card>

  <Card title="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
  </Card>
</Columns>

## Before you start

You need three things:

1. An **API key** for your backend (`Authorization: Bearer sk_prod_…`). [Create one in the portal](/account/api-keys). It must stay server-side; see [Authentication](/api-reference/authentication).
2. Your **`programId`**, the identifier for your pass program, used in every create and lookup call. Find it with [List programs](/api-reference/programs/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](/programs/webhooks).

## 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 if convenient. If not, look it up by `programId` + `externalId`.

**Wallet links.** Add to Wallet links are short-lived: roughly 15 minutes for the Apple Wallet link, roughly an hour for the Google Wallet save link. Each response carries the exact deadline in `expiresAt`. Request links at click time, and never cache or store them.

**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](/api-reference/integration/in-store).

## Endpoint summary

The complete surface a typical integration touches:

| Purpose                                  | Endpoint                                                                                                 |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Look up an existing pass by `externalId` | [List passes](/api-reference/passes/list-passes)                                                         |
| Issue a pass                             | [Create new pass](/api-reference/passes/create-new-pass)                                                 |
| Update a pass                            | [Update pass](/api-reference/passes/update-pass)                                                         |
| Get an Apple Wallet link                 | [Generate Apple Wallet installation link](/api-reference/passes/generate-apple-wallet-installation-link) |
| Get a Google Wallet link                 | [Generate Google Wallet save link](/api-reference/passes/generate-google-wallet-save-link)               |
| Record a transaction (optional)          | [Create transaction](/api-reference/transactions/create-transaction)                                     |
| Void a pass                              | [Void pass](/api-reference/passes/void-pass)                                                             |

Inbound to you: [webhook deliveries](/programs/webhook-deliveries), signed POSTs to your endpoint when a pass changes status or a transaction is recorded.