Shopify App

​

Deployment topology

• SHOPIFY_EDGE=1 (recommended) — a dedicated second deployment whose only job is Shopify traffic. isBlockedInEdgeMode 404s every path except /api/shopify/* and the two health probes (/api/health, /api/ready) — so a public, unauthenticated, internet-facing surface (webhooks, App Proxy calls, the embedded admin, the checkout web pixel) can never reach the rest of the platform’s routes through this deployment, even under a traffic flood or a bug in the Shopify surface itself. It queries the same Postgres database directly (reads/writes ShopifyShop, ShopifyAppConfig, webhook dedupe records, GDPR erasure state, etc.) and forwards every recommend/respond call to the core deployment over HTTP, authenticated as the relevant tenant’s own scoped edge API key.
• SHOPIFY_SERVE_ON_CORE=1 (single-service opt-in, the quickstart default) — the same core deployment additionally answers the credential-less Shopify routes itself, with no additional blast-radius isolation: /api/shopify/* traffic runs in the same process as every /api/v1/* route and the Studio UI, sharing the same resources and attack surface. This is a genuine tradeoff, not a free simplification — it removes the isolation the dedicated edge provides in exchange for running one fewer service. Appropriate for a low-traffic or trusted-network deployment where a second service isn’t worth the operational overhead; the dedicated edge remains the recommended default for anything internet-facing at scale.

​

Required environment variables

​

Required app scopes

​

Embedded admin static serving

• Gate: exactly the same as every other Shopify route — isShopifyEdgeDeployment() (SHOPIFY_EDGE=1 or SHOPIFY_SERVE_ON_CORE=1). Neither flag set → every /shopify-admin/* path 404s (isShopifyAdminAssetBlocked in middleware.ts), matching the playground default.
• SPA fallback: next.config.js rewrites any extensionless path under the prefix (e.g. /shopify-admin/offers, or the bare /shopify-admin) to /shopify-admin/index.html, so client-side routes survive a hard refresh. Genuine static assets (/shopify-admin/assets/*.js/.css) are excluded from the rewrite and served directly.
• Framing: the document response’s X-Frame-Options is dropped and the CSP’s frame-ancestors directive is scoped to the requesting shop’s own domain (read from the response’s own ?shop= query param, validated against *.myshopify.com) plus https://admin.shopify.com — Shopify iframes the app inside admin.shopify.com, and per-shop scoping is Shopify’s documented requirement, not a blanket wildcard.
• App Bridge script: the document response’s CSP script-src also carries https://cdn.shopify.com, the only origin App Bridge v4 loads from (shopify/admin/src/lib/bootstrap.ts’s <script src="https://cdn.shopify.com/shopifycloud/app-bridge.js">) — confirmed against Shopify’s own shopify_app gem CSP helper docs, which document adding exactly that URL to script-src for App Bridge and don’t document any connect-src widening; this deployment’s own API calls from the SPA are same-origin, so connect-src stays 'self'. This admin-scoped CSP is rebuilt from scratch for the document response and always wins, even when an operator has set CSP_POLICY for the rest of the app (lib/shopify/admin-csp.ts’s applyShopifyAdminFrameHeaders) — App Bridge’s script-src need and the per-shop frame-ancestors are both non-negotiable for this one surface; CSP_POLICY still governs every non-/shopify-admin response unchanged. Static asset responses (JS/CSS bundles) aren’t documents, so only frame-ancestors is appended to whatever CSP is already present there.
• Caching: the document response (any extensionless path — the one that carries the per-shop frame-ancestors CSP above) is served with Cache-Control: no-store. This is deliberate: that response is NOT safely cacheable behind a shared/CDN cache without a Vary on the shop, since a cached response for one shop could otherwise be served to a different shop with the wrong frame-ancestors, breaking that shop’s iframe embed. Content-hashed static assets under the same prefix aren’t touched by this and remain cacheable.

​

GET /api/v1/settings/integrations/shopify/deploy-kit

• shopify.app.toml — the canonical file (shopify/shopify.app.toml) with its maintainer-only header comment stripped, client_id substituted with this tenant’s real Client ID, and all 5 edge-pending.kaireonai.com sentinel occurrences replaced with this deployment’s resolved public base URL (a straight substring substitution, so whatever path suffix already follows the sentinel in the canonical file survives unchanged — application_url keeps its /shopify-admin suffix, the other 4 keep their own /api/shopify/* suffixes).
• extensions/ — every storefront/checkout extension source, unmodified, bundled at image-build time by tools/scripts/bundle-shopify-kit.sh.
• package.json / package-lock.json / .gitignore — the npm workspace root the extensions build under.
• deploy.sh — npm install && npx shopify app deploy, plus a printed reminder about the one-time network-access approval (see the integration guide). Ships with the executable bit set; README.md (also injected) documents bash deploy.sh as a fallback for unzip clients that don’t preserve it, and notes the zip has no wrapping top-level folder — unzip into an empty directory.

​

Auth: lookup-then-verify

1. Lookup — extract an UNVERIFIED shop identifier from the request (the App Proxy’s shop query param, the webhook’s X-Shopify-Shop-Domain header, or a JWT’s dest/aud claim decoded without checking its signature) and use it purely as a key into ShopifyAppConfig (resolveCredentialsForShop / resolveCredentialsByClientId) to find which tenant’s secret to try.
2. Verify — check the request’s actual signature (HMAC, App Proxy signature, or JWT signature) against THAT tenant’s own resolved secret. A forged/spoofed identifier at worst picks the wrong tenant’s secret to verify against, and verification then fails exactly as it would for any other invalid signature — the unverified lookup step grants no authority by itself.

​

Rate limits

​

Never-5xx storefront contract

​

Install

​

POST /api/shopify/install

{
  "shopDomain": "my-store.myshopify.com",
  "sessionToken": "<App Bridge ID token>"
}

{ "tenantId": "..." }

​

Webhooks

​

POST /api/shopify/webhooks

​

Attribution

​

Customer sync

• upsertShopifyCustomer (customers/create/customers/update, and the install-time backfill below) — INSERT ... ON CONFLICT (customer_id) DO UPDATE that refreshes identity + aggregates + tiers but deliberately never touches the three affinity columns, so a profile refresh can’t clobber affinity accumulated by order webhooks.
• applyOrderAffinity (orders/create) — refreshes recency + tiers + affinity arrays only; NEVER touches total_spent/orders_count/avg_order_value on the row-exists path, since those are owned exclusively by the authoritative customers/* upsert (Shopify’s own amountSpent/numberOfOrders already include every order) — incrementing them here would double-count. If no row exists yet (the order arrived before any customers/create webhook or backfill), it bootstraps a stub row from that one order’s total instead of dropping the signal; the next customers/* upsert overwrites it with the real absolute value.
• syncCustomerFromOrder (orders/create, immediately after applyOrderAffinity) — fetches that SAME customer’s own authoritative amountSpent/numberOfOrders via a single-customer Admin GraphQL query and writes them through upsertShopifyCustomer’s absolute-overwrite path. Exists because Shopify does not reliably follow an order with a customers/update webhook carrying the recomputed lifetime spend (most notably orders placed from the Shopify admin) — without this fetch, total_spent/orders_count (and their derived spend_tier/frequency_bucket) could go stale even though the order landed and Shopify’s own customer page shows the real total. A fresh read, not an increment, so a webhook retry or duplicate delivery converges to the same authoritative number rather than compounding. Isolated the same way as applyOrderAffinity: a GraphQL failure here is logged and swallowed, never undoing attribution or affinity that already succeeded, and never fails the webhook. Only runs for an order with a resolvable customer id (a guest order has nothing to sync). Subject to the same Protected Customer Data gating as every other customer GraphQL call — a shop without approval gets email/firstName/lastName/defaultAddress nulled on this query, but amountSpent/numberOfOrders are never PII-gated and still come through (see the integration guide’s Protected Customer Data note).
• Install-time backfill (backfillCustomers) — fires in the background (not awaited by POST /api/shopify/install, so it never delays the install response) on every fresh install AND every reprovision/reinstall: paginated GraphQL sync of the full customer catalog (authoritative aggregates), then a second pass replaying the last 90 days of orders for recency/affinity. Capped at MAX_BACKFILL_PAGES (200) pages per pass (50 records/page) — a truncation is logged, never silent, and the ongoing webhooks continue filling in the gap over time.

​

App Proxy (storefront)

​

GET /api/shopify/proxy/recommend

{ "cards": [PublicOfferCard, ...] }

interface PublicOfferCard {
  rid: string;          // the recommended Creative's id — stamp this back via _kaireon_rid
  offerId: string;
  name: string;
  imageUrl: string | null;
  price: string | null;     // Shopify's raw display string, e.g. "24.99"
  ctaText: string;          // defaults to "Shop Now"
  variantId: string | null; // numeric Shopify variant id for /cart/add.js, if synced
}

​

POST /api/shopify/proxy/outcome

{
  "rid": "<Creative id from the recommend response>",
  "outcome": "impression" | "click" | "add_to_cart" | "dismiss",
  "anon": "anon_..."
}

​

Ingest (checkout web pixel + Thank You page)

​

POST /api/shopify/ingest

{
  "shopDomain": "my-store.myshopify.com",
  "events": [
    { "name": "checkout_started" | "checkout_completed", "anon": "anon_...", "checkoutToken": "..." }
  ]
}

​

GET /api/shopify/ingest/thankyou-offer

• 401 — the token is missing/malformed, its signature doesn’t verify, OR its dest names a shop with no ShopifyShop row or whose tenant has no ShopifyAppConfig at all. Under per-tenant secrets there’s no way to verify a token for a shop that was never provisioned, so this case 401s rather than silently degrading — closing what used to be a way to distinguish “never provisioned” from “provisioned but not installed” using nothing but a validly-signed token.
• 200 { "cards": [] } — the token verifies fine, but the resolved shop’s status isn’t installed (or the request has no resolvable customer identity, e.g. a guest checkout). This is the storefront-safe degrade path: a real store mid-uninstall never breaks the Thank You page with an error.

​

POST /api/shopify/ingest/thankyou-outcome

{
  "rid": "<Creative id from the thankyou-offer response>",
  "outcome": "impression" | "click"
}

​

Admin bundle bootstrap

​

GET /api/shopify/app-config

​

Embedded admin

​

GET / PUT /api/shopify/admin/offers

{
  "data": [
    {
      "id": "...", "name": "...", "status": "active" | "draft" | "archived",
      "price": 24.99, "shopifyProductId": "gid://shopify/Product/123",
      "imageUrl": "...", "merchantTouched": true,
      "surfaces": ["shopify_product_page"], "capPerWeek": 5
    }
  ],
  "pagination": { "limit": 50, "cursor": "...", "hasMore": true }
}

{ "updates": [{ "offerId": "...", "activate": true, "surfaces": ["shopify_product_page"], "capPerWeek": 5 }] }

• surfaces decides which of the four storefront channels have an active creative for that offer. Every imported offer already has one creative per surface; toggling a surface flips its creative between active and draft (creatives are never deleted, so re-enabling is instant). An offer with no active creative on a surface can’t be recommended there — the recommend pipeline drops any candidate that has no creative for the requested channel.
• capPerWeek maps to a per-offer frequency_cap contact policy (scope="offer", config.maxPerWeek) that the decisioning engine enforces per candidate. Clearing it to 0 removes the policy (no cap); it is never written as maxPerWeek: 0, which the engine would read as “block entirely.”

​

GET /api/shopify/admin/surfaces

{
  "data": [
    {
      "shopDomain": "my-store.myshopify.com",
      "surfaces": [{ "key": "shopify_product_page", "label": "Product page", "status": "active", "enabled": true }, ...]
    }
  ]
}

​

GET /api/shopify/admin/performance

{
  "period": { "days": 7 },
  "data": [{ "offerId": "...", "name": "...", "impressions": 100, "clicks": 12, "revenue": 240.50, "conversionRate": "12.0%" }]
}

​

GET / PUT /api/shopify/admin/settings

{ "autoDraftNew": true }

​

POST / GET /api/shopify/admin/import

{ "created": 3, "updated": 12, "skipped": 1 }

​

Settings API (per-tenant credentials + store list)

​

GET /api/v1/settings/integrations/shopify

{
  "configured": true,
  "clientId": "0efcc19c536d2166de1730349d9f16a4",
  "secretSet": true,
  "lastVerifiedAt": "2026-07-06T12:00:00.000Z",
  "stores": [
    {
      "shopDomain": "my-store.myshopify.com",
      "status": "installed",
      "installedAt": "2026-07-01T00:00:00.000Z",
      "offersImported": 42,
      "lastReconciledAt": "2026-07-06T06:00:00.000Z"
    }
  ]
}

​

PUT /api/v1/settings/integrations/shopify

​

DELETE /api/v1/settings/integrations/shopify

​

POST /api/v1/settings/integrations/shopify/resync-customers

​

Reconciliation

​

GET /api/v1/cron/shopify-reconcile

​

Storefront extensions reference