App Lifecycle

Every app on LaunchMyStore moves through the same lifecycle: a merchant discovers it in the marketplace, installs it (granting OAuth scopes), uses it (your code runs in their store), and eventually uninstalls it. This page is a single reference for every event your app will receive at each stage and what your handlers should do.

Lifecycle States

   ┌──────────────┐                  ┌──────────────┐
   │ Marketplace  │  install         │              │
   │   Listing    │ ───────────────▶ │  installed   │
   └──────────────┘                  │              │
                                     └──────┬───────┘
                                            │
                       ┌──────── publish ───┤
                       │     new version     │
                       ▼                     │
                  ┌─────────┐                │
                  │ updated │                │
                  └────┬────┘                │
                       │                     │
                       └─────────────────────┘
                                            │
                                            │ uninstall
                                            ▼
                                     ┌──────────────┐
                                     │ uninstalled  │
                                     └──────────────┘

State	App can call APIs?	Webhooks delivered?	Extensions render?
Listing only	No	No	No
Installed	Yes	Yes	Yes
Uninstalled	No (revoked)	Final `app/uninstalled` only	No

1. Discovery & Install

Merchants discover apps in the marketplace and click Install. This kicks off the OAuth flow.

Install flow (high level)

Apps receive their first token through the managed install handoff — there is no app-initiated browser redirect to /apps/oauth/authorize (that endpoint is a merchant-authenticated JSON API used by the admin):

Merchant clicks "Install" (marketplace / Developer Portal)
        ↓
Merchant approves scopes on the in-admin consent screen
        ↓
Browser → {appUrl}/auth?shop=...&domainSlug=...&storeId=...&code=...&state=...&host=...&timestamp=...&hmac=...
        ↓
Your app: verify hmac, then POST /apps/oauth/token { grant_type: 'authorization_code', code, state, client_id, client_secret }
        ↓
Response: { status, state, data: { access_token, refresh_token, token_type, expires_in, scope } }

data.scope is a single space-delimited string of granted scopes. See Authentication and Install handoff for the full code walkthrough.

How the admin embeds your app

Once installed, opening the app in the admin loads your app’s root in an iframe. Three details trip up most first integrations:

{appUrl}/?host=<base64 admin origin>&shop=<storefront host>&storeId=<uuid>&apiKey=<client_id>&timestamp=<ms>

Serve your entry point at /

The admin embeds the app root — it has no way to know which of your pages is the entry point. If / is unrouted, merchants see your framework’s bare 404 (Cannot GET /) inside the iframe. Redirect / to your home page and preserve the query string — it carries everything below.

Sub-pages load as {appUrl}/<path>, without any prefix

Navigating to an admin sub-path requests {appUrl}/settings, not {appUrl}/admin/settings. If your pages live under a prefix, serve or redirect the bare paths too.

One merchant, three identifiers — register all of them

shop is the full storefront host (acme.launchmystore.io, or the merchant’s custom domain). storeId is the immutable UUID — prefer it for keying per-merchant state, since shop changes when a merchant moves to a custom domain. domainSlug is the canonical slug the App Proxy uses.These are not interchangeable, and different surfaces send different ones: this handoff carries all three, while a storefront App Proxy request carries only shop=<domainSlug> and never storeId. An app that keys its storage on whichever arrived first splits one merchant into two tenants — buyer-facing writes land in one bucket while the merchant’s admin reads another, with no error to show for it.Store one record at install and alias every identifier to it.

Do not derive the slug with shop.split('.')[0]. On a custom domain that collapses every www.<brand>.com store to the single slug www, so unrelated merchants share one entry — one merchant’s credentials serving another merchant’s store. Use the domainSlug param above.

These query params are a hint, not authentication. The only trustworthy tenant identity is the verified App Bridge session token (Session tokens); treat shop / storeId in the URL as user-supplied.

Install rejection — per-shop function caps

If your app declares one or more functions in app.json and the merchant’s store already has the maximum number of active apps shipping that function type, both install paths reject the install with HTTP 409 Conflict:

Direct merchant install: POST /apps/store/install/:appId
OAuth code exchange: POST /apps/oauth/token with grant_type=authorization_code

Response shape:

{
  "status": 409,
  "state": "error",
  "message": "Cannot install: this store already has 1 active cart_transform function, and the per-shop limit is 1. Uninstall another cart_transform app before installing this one."
}

Your installer / OAuth callback should surface the message field directly — it names the offending function type and the current cap so the merchant knows what to uninstall. See Functions › Active-Install Caps Per Shop for the per-type limits.

Re-issuing tokens for an already-active installation never triggers the cap check — only new activations are counted. A previously-uninstalled app that the merchant is re-installing also passes the check as long as the cap still has headroom.

`app/installed` webhook

Fired immediately after the install completes. Use this to:

Provision merchant-side resources (DB row, default settings)
Send a welcome email
Sync initial data via the granted scopes

The request body is the payload itself — there is no envelope. The topic travels in the X-LMS-Topic header, the delivery id in X-LMS-Webhook-Id, and the shop host in X-LMS-Shop-Domain:

POST /your-webhook-endpoint
X-LMS-Topic: app/installed
X-LMS-Webhook-Id: 6f1e...-uuid
X-LMS-Shop-Domain: merchant-store.launchmystore.io

{
  "appId": "app_01H...",
  "installationId": "inst_01H..."
}

The app/installed webhook fires after the OAuth redirect — your redirect handler should not assume any merchant-side state has been created yet. Either bootstrap your DB row inside the OAuth handler (synchronous, blocks the redirect) or render a “Setting up…” page that polls until the webhook completes.

2. Active Use

Once installed, your app can:

Call any /api/v1/* endpoint with the access token (subject to granted scopes)
Receive any webhook the merchant has subscribed (or that you registered at install time)
Have its extensions rendered into storefronts, checkouts, and admin pages
Have its functions executed during cart verification and order placement flows

Token refresh

Access tokens expire after 24 hours. Refresh tokens last 30 days. Always implement refresh:

async function getValidToken(installation) {
  if (Date.now() < installation.expiresAt - 60_000) {
    return installation.accessToken;
  }
  const r = await fetch('https://api.launchmystore.io/apps/oauth/token', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'refresh_token',
      refresh_token: installation.refreshToken
    })
  });
  const { data: tokens } = await r.json();   // unwrap the { status, state, data } envelope
  await storeTokens(installation.id, tokens);
  return tokens.access_token;
}

If the refresh token has also expired (30+ days of inactivity), the merchant must re-authorize.

3. Uninstall

Merchants can uninstall an app at any time from their admin. When they do:

OAuth tokens are revoked immediately — your app cannot make any further API calls
Extensions are unmounted — blocks/checkout/admin extensions stop rendering
app/uninstalled webhook fires (this is the only webhook your app receives after uninstall)
Webhook subscriptions are cleared

`app/uninstalled` webhook

Body is the payload itself; the topic is in the X-LMS-Topic header:

POST /your-webhook-endpoint
X-LMS-Topic: app/uninstalled
X-LMS-Webhook-Id: 41ac...-uuid

{
  "appId": "app_01H..."
}

Cross-reference appId against your own install records (keyed by storeId from the install handoff) — the payload does not carry an uninstall reason or timestamp. Use this to:

Clean up merchant data (or schedule it — see GDPR below)
Cancel any active subscriptions / usage charges
Send an “we’d love your feedback” email
Update internal analytics

app/uninstalled is delivered with a 3-retry exponential backoff (1m / 5m / 15m). If your endpoint is down for the full retry window, the webhook is dropped — but the uninstall still happens. Always reconcile with the installations list endpoint on a daily cron rather than relying on the webhook alone.

Three additional webhooks satisfy GDPR / CCPA obligations. Subscribing to these is mandatory for any app published to the public marketplace.

`customers/data_request`

Fires when a merchant or customer requests a data export.

{
  "topic": "customers/data_request",
  "data": {
    "shopDomain": "merchant.example.com",
    "customerId": 1234567,
    "customerEmail": "shopper@example.com",
    "ordersRequested": [9876, 9877]
  }
}

Within 30 days, you must compile every piece of customer data your app stores and email it to the merchant (the merchant then forwards to the customer).

`customers/redact`

Fires when a customer-redaction request is submitted (merchant/staff create it via the GDPR endpoints — POST /apps/gdpr/customer-redact).

{
  "topic": "customers/redact",
  "data": {
    "shopDomain": "merchant.example.com",
    "customerId": 1234567,
    "customerEmail": "shopper@example.com",
    "ordersToRedact": [9876, 9877]
  }
}

You must permanently delete or anonymize all data tied to this customer within 30 days of receiving this webhook. See GDPR Reference for the audit trail format.

`shop/redact`

Fires when a shop-redaction request is submitted (POST /apps/gdpr/shop-redact) — typically after an uninstall when the merchant wants their data purged. It is not scheduled automatically after app/uninstalled.

{
  "topic": "shop/redact",
  "data": {
    "shopDomain": "merchant.example.com",
    "shopId": 12345,
    "uninstalledAt": "2026-05-04T12:00:00Z"
  }
}

You must permanently delete all merchant-tied data within 30 days. Keep data intact until you actually receive shop/redact — an uninstall alone is not a deletion request, and merchants often reinstall.

Webhook Delivery Guarantees

Signature: HMAC-SHA256 (base64) of the raw request body, sent in the X-LMS-Hmac-SHA256 header. The signing secret depends on how the webhook was registered: API-registered subscriptions (POST /api/v1/webhooks.json) are signed with the per-subscription secret returned once in the create response; manifest-declared (extensions.webhooks[]) and GDPR webhooks are signed with your clientSecret. Legacy rows with no secret are delivered unsigned. See Webhook Verification. Always verify before processing.
Retries: 3 attempts with exponential backoff (1m, 5m, 15m). After the 3rd failure, the event is dropped.
Ordering: Best-effort, not guaranteed. Use createdAt to sequence; use idempotency keys (e.g. installationId + topic + createdAt) to dedupe.
At-least-once: A successful response (2xx) acks the event. Missing the ack causes a retry — your handler must be idempotent.

See Webhook Verification for the HMAC signature code.

Testing Webhooks Locally

Waiting for a real merchant install, order, or GDPR request just to verify a handler works is painful — and some events (like customers/redact) are nearly impossible to reproduce on demand. The lms webhook trigger CLI command generates a sample payload for any topic, signs it with your app’s clientSecret, and POSTs it to a local URL so you can exercise your handler end-to-end.

Install the CLI

The command ships with the LaunchMyStore CLI. If you haven’t set it up yet, see CLI Setup. Once configured, your clientSecret is read from LMS_CLIENT_SECRET or .lmsrc.json, so most invocations need only the topic.

Common scenarios

# Fire a sample order at your local handler
lms webhook trigger orders/create

# Override the URL if your handler isn't on the default port
lms webhook trigger orders/create --url http://localhost:4000/api/webhooks

# Verify your data-deletion handler runs without waiting 48h
# for a real merchant-approved redact request
lms webhook trigger customers/redact

# Reproduce a specific event from a captured production payload
lms webhook trigger orders/paid --payload-file ./fixtures/order-12345.json

# Or pass JSON inline
lms webhook trigger products/create --payload '{"id":"prd_test","title":"Demo"}'

Headers it sends

Each request mirrors what production webhook delivery sends, so the same verification code path runs in dev:

Header	Value
`Content-Type`	`application/json`
`X-LMS-Topic`	The topic you passed (e.g. `orders/create`)
`X-LMS-Webhook-Id`	Random UUID — useful for dedupe testing
`X-LMS-Delivery-Attempt`	`1` (bump manually if you want to test retry behavior)
`X-LMS-Hmac-SHA256`	Base64 HMAC-SHA256 of the raw body. The CLI signs with the secret you configure (`LMS_CLIENT_SECRET` / `.lmsrc.json`) — set it to whichever secret your handler verifies against (the per-subscription `secret` for API-registered webhooks, or your `clientSecret` for manifest/GDPR webhooks) so the exact production verification path runs

Your handler should verify X-LMS-Hmac-SHA256 against the raw request body before doing anything else. See Webhook Verification for the exact comparison code.

Pair lms webhook trigger with a local tunnel (e.g. ngrok) to test handlers that need to call back into the LaunchMyStore API. Configure the CLI with the same signing secret your handler verifies against so the production verification code path runs unchanged in dev.

Lifecycle Checklist

Before you publish your app to the marketplace, your handler must:

Handle OAuth callback (`/oauth/callback`)

Exchange code for tokens, create your installation row, redirect merchant to your dashboard.

Handle `app/installed` webhook

Idempotent provisioning — running it twice should not duplicate data.

Refresh tokens before they expire

Background job or just-in-time refresh inside your API client.

Handle `app/uninstalled`

Mark installation as inactive, schedule data retention timer.

Handle `customers/data_request`, `customers/redact`, `shop/redact`

Required for marketplace approval — compile/delete data within 30 days.

Authentication — OAuth flow code walkthrough
App Versioning — draft/publish/deprecate flow + per-install rollback
GDPR Reference — full payloads + retention windows
Webhooks Overview — delivery guarantees + topic list

Get Started

Guides

Extensions

Functions

App Bridge

Billing

AI & MCP

App Lifecycle

App Lifecycle

Lifecycle States

1. Discovery & Install

Install flow (high level)

How the admin embeds your app

Install rejection — per-shop function caps

`app/installed` webhook

2. Active Use

Token refresh

3. Uninstall

`app/uninstalled` webhook

`customers/data_request`

`customers/redact`

`shop/redact`

Webhook Delivery Guarantees

Testing Webhooks Locally

Install the CLI

Common scenarios

Headers it sends

Lifecycle Checklist

​App Lifecycle

​Lifecycle States

​1. Discovery & Install

​Install flow (high level)

​How the admin embeds your app

​Install rejection — per-shop function caps

​app/installed webhook

​2. Active Use

​Token refresh

​3. Uninstall

​app/uninstalled webhook

​4. GDPR Lifecycle Webhooks

​customers/data_request

​customers/redact

​shop/redact

​Webhook Delivery Guarantees

​Testing Webhooks Locally

​Install the CLI

​Common scenarios

​Headers it sends

​Lifecycle Checklist

​Related

App Lifecycle

Lifecycle States

1. Discovery & Install

Install flow (high level)

How the admin embeds your app

Install rejection — per-shop function caps

`app/installed` webhook

2. Active Use

Token refresh

3. Uninstall

`app/uninstalled` webhook

4. GDPR Lifecycle Webhooks

`customers/data_request`

`customers/redact`

`shop/redact`

Webhook Delivery Guarantees

Testing Webhooks Locally

Install the CLI

Common scenarios

Headers it sends

Lifecycle Checklist

Related