# BillDog

> Paywalls, analytics, messaging, surveys, journeys and auth for mobile and web apps — one SDK, one dashboard.

Every page below is also available as Markdown by appending `.md` to its URL.
The full text of all of them is at /llms-full.txt.
To wire the SDK into an app, start at /SKILL.md.

## API contract (from openapi.yaml)

### Who a request acts for

- **secret_key** (`apiKey`): A project secret key (bd_secret_live_… / bd_secret_test_…, owner_kind project, permissions.write true). May act on any customer of its project, named by customer_id or app_user_id.
- **session** (`billdogSession`): A BillDog Auth access token in X-BillDog-Session. Acts only on the session's own customer.
- **device** (`billdogDevice`): X-BillDog-Device (the install's anonymous id, prefix $BillDogAnonymousID:) plus X-BillDog-Device-Key (bdk_ + 43 base64url characters). Acts only on the device's own anonymous customer. The SDKs send both on every request.
- **none** (`apiKey`): A public key alone proves which project is asking and nothing about a person. Customer-scoped endpoints refuse it with 403 PROOF_REQUIRED.

- Body selectors (customer_id, app_user_id, user_id) never decide who the caller is. A selector that names someone other than the proven customer is 403 ACCESS_DENIED with details.reason target_mismatch.
- An invalid proof is 401 PROOF_INVALID and is never downgraded to a weaker principal.
- The static identity hash is removed. Presenting X-BillDog-Identity-Hash or a body identity_hash is 401 PROOF_INVALID with details.reason unsupported.
- Money and account erasure need a session signed in within the last 900 seconds, else 403 REAUTH_REQUIRED. A project secret key is not aged.
- A store purchase has one owner per (project, environment, platform, store subscription id). A receipt posted by another customer moves the purchase only when it is paid and the project's receipt_collision_policy is transfer; otherwise 409 PURCHASE_OWNER_CONFLICT.

### Error codes

Envelope: `{ success: false, error: { code, message, details }, meta }`.

- `PROOF_REQUIRED` (403): 403 `PROOF_REQUIRED`.
- `PROOF_INVALID` (401): 401 `PROOF_INVALID`.
- `REAUTH_REQUIRED` (403): 403 `REAUTH_REQUIRED`.
- `ACCESS_DENIED` (403): 403 `ACCESS_DENIED` with `details.reason: 'target_mismatch'` and `details.selector` (`customer_id`, `app_user_id`, `token`): the body names a customer other than the one the caller proved.
- `CUSTOMER_NOT_FOUND` (404): 404 `CUSTOMER_NOT_FOUND`.
- `PURCHASE_OWNER_CONFLICT` (409): 409 `PURCHASE_OWNER_CONFLICT`.
- `PLACEMENT_NOT_FOUND` (404): 404 `PLACEMENT_NOT_FOUND` (headless mode).

### Headless placement contract (`POST /get-wall-for-placement`)

Source: `supabase/functions/get-wall-for-placement/index.ts`.

`render_mode: "hosted"` (default): `placement_identifier` is required;
`paywall` carries the device-category `configurations`, complete — the
same answer `fetch-paywall` builds (`buildHostedWallAnswer`), with
`resources` beside it — so a client renders it as returned and never
fetches the wall again; an unknown
placement is created on first sighting (`source: 'sdk_autocreated'`);
a gated placement whose content is withheld for this caller is
403 `PLACEMENT_ACCESS_WITHHELD`. Supports `If-None-Match` / `ETag`.

`render_mode: "headless"` (bring your own UI): `placement_identifier`
is optional. Omitted → the project's offering for this caller (an
offering audience rule that matches, else the `is_default` offering,
else the `is_current` one); `placements` is not read. Given → what that
placement resolves to (campaign, then the placement's own offering).
A headless read never reads or returns a wall (`paywall` is always
null) and never writes a placement row. An unknown placement is
404 `PLACEMENT_NOT_FOUND`, never the default. Holdout / gated /
withheld outcomes are HTTP 200 with `offering: null` and the reason in
`presentation`. `offering` is THE selection: in `offerings`,
`is_current` is true on exactly that one. `entitlements` is the
project's entitlement catalogue, not the caller's grants. Clients
never send the literal placement `default`.

Caller identity (`resolveCallerCustomer`): WHO the placement is
resolved for comes from the proof. A device key is its own anonymous
customer (created here if new; a body `app_user_id` label is ignored,
a `customer_id` must be its own). A session is its own customer (a body
label must be one of its own labels). A project secret key names a
customer with `customer_id` (a customers.id UUID) or `app_user_id` (a
label; an unknown label is bucketed as-is without creating anything). A public key alone
resolves for nobody: targeting and bucketing run anonymously, and no
body field can name another customer. A selector naming someone else
is 403 `ACCESS_DENIED` (`target_mismatch`).

### Endpoints

Base URL: `https://hbumxgdhjkgunydxftom.supabase.co/functions/v1`. Every endpoint answers the `{ success, data, meta }` envelope.

- POST /auth-config — What this project requires before a sign-up is accepted (API key)
- POST /auth-sign-up — Begin a sign-up (API key)
- POST /auth-prepare — Send a one-time code (API key)
- POST /auth-attempt — Submit a factor (API key)
- POST /auth-token — Refresh a session (API key)
- POST /auth-revoke — Sign out (API key)
- POST /auth-sessions — List a user's sessions (API key)
- POST /auth-introspect — Is this token live right now? (API key)
- GET /auth-jwks — Public keys for offline verification (no key)
- POST /auth-set-password — Set a password — by reset code, or as a signed-in change (API key)
- POST /auth-account — The signed-in user's own account view (API key)
- POST /auth-user-factors — Manage second factors (API key)
- POST /auth-passkey — WebAuthn registration and sign-in (API key)
- POST /auth-org — Organizations, members, invitations and domains (API key)
- POST /auth-oauth-verify — Exchange a provider ID token for a session (API key)
- POST /auth-oauth-start — Begin a redirect sign-in (PKCE) (API key)
- POST /auth-oauth-callback — Complete a redirect sign-in (API key)
- POST /auth-sso-start — Route a work email to its enterprise connection (API key)
- POST /auth-sso-callback — Complete an OIDC enterprise sign-in (API key)
- POST /auth-sso-acs/{connection_id} — SAML assertion consumer service (no key)
- GET /auth-sso-acs/{connection_id}/metadata — SP metadata for the IdP (no key)
- POST /manage-auth-settings — Project auth settings, SSO connections, SCIM tokens and signing keys (dashboard session)
- POST /manage-jwt-templates — List, upsert, delete or preview the extra claims a session token carries (API key)
- POST /auth-provision-keys — Provision or rotate signing keys (dashboard session)
- POST /auth-import — Import users from Clerk, Auth0 or Firebase (dashboard session)
- POST /auth-impersonate — Act as a user, for support (dashboard session)
- GET /scim-v2/Users — List or filter provisioned users (SCIM token)
- POST /scim-v2/Users — Provision a user (SCIM token)
- PATCH /scim-v2/Users/{id} — Update or deactivate a user (SCIM token)
- DELETE /scim-v2/Users/{id} — Deprovision a user (SCIM token)
- GET /scim-v2/Groups — List directory groups (SCIM token)
- GET /scim-v2/ServiceProviderConfig — Advertised SCIM capabilities (SCIM token)
- POST /sdk-config — Get remote project-level configuration for SDKs (API key)
- POST /sdk-renderer-version — Fetch renderer version info for SDK updates (no key)
- POST /ingest-events — Batch ingest multiple analytics and paywall events (API key)
- POST /list-walls — List active paywalls for a project (API key)
- POST /fetch-wall — Fetch paywall configuration (API key)
- POST /feedback — Submit customer feedback or support ticket (no key)
- POST /update-subscription-notification — Update scheduled, sent, or cancelled local subscription notification status (API key | API key + session | API key + device key)
- POST /create-stripe-portal-session — Create a Stripe customer billing portal session link (API key)
- POST /public-analytics-api — Query project analytics via a public BI connector endpoint (no key)
- POST /promote-entitlement — Manually grant or revoke promotional entitlements (API key)
- POST /compute-entitlements — Retrieve consolidated entitlement grants and subscription statuses for customer (API key | API key + session | API key + device key)
- POST /experiment-config — Assign variant allocations and variables for user (API key | API key + session | API key + device key)
- POST /experiment-event — Track exposure or conversion for experiment (API key | API key + session | API key + device key)
- POST /feature-flag-definitions — Fetch raw flag criteria for local evaluation (no key)
- POST /record-campaign-event — Track conversion funnel metrics for marketing campaigns (API key | API key + session | API key + device key)
- POST /redeem-purchase — Redeem the token of a completed web checkout and grant its entitlements (API key | API key + session | API key + device key)
- POST /web-checkout-status — How one web checkout of the proven customer stands (API key | API key + session | API key + device key)
- POST /generate-offer-signature — Sign an App Store promotional offer for StoreKit (API key)
- POST /sdk-create-test-purchase — Record a simulated Test Store purchase for a sandbox test user (API key)
- POST /set-customer-attributes — Update core billing database contact details for customer (API key | API key + session | API key + device key)
- POST /get-subscriptions — Retrieve active subscriber subscriptions and entitlements (API key | API key + session | API key + device key)
- POST /validate-api-key — Validate API key (API key)
- POST /list-offerings — List all offerings for a project (API key)
- POST /create-offering — Create a new offering (API key)
- POST /update-offering — Update an existing offering (API key)
- POST /delete-offering — Delete an offering (API key)
- POST /list-offering-packages — List packages for an offering (API key)
- POST /manage-offering-packages — Add or remove packages from an offering (API key)
- POST /fetch-paywall — Fetch one named paywall (API key | API key + session | API key + device key)
- POST /fetch-paywall-draft — Fetch a paywall's draft configuration (preview tooling) (API key)
- POST /list-paywalls — List the project's active paywalls (metadata only) (API key)
- GET /get-preview-paywall — Resolve a paywall preview link (QR code / share link) by its token (no key)
- POST /get-preview-paywall — Preview a wall from the dashboard (dashboard session)
- POST /check-wall-version — Check if paywall has updates (API key)
- POST /check-offering-version — Check if offering has updates (API key)
- POST /list-placements — List all placements for a project (API key)
- POST /manage-placement — Create, update or delete a placement, or set its offerings (API key)
- POST /get-customer-info — The customer's subscriptions, entitlements, contact fields and attribution (API key | API key + session | API key + device key)
- POST /check-entitlement — Does this customer hold this entitlement (API key | API key + session | API key + device key)
- POST /process-purchase — Record a store purchase (v1; maps onto the store-evidence ledger) (API key | API key + session | API key + device key)
- POST /restore-purchases — Re-affirm a customer's grants and return them (API key | API key + session | API key + device key)
- GET /health-check — Check API health status (no key)
- POST /check-trial-eligibility — Check customer trial eligibility (API key | API key + session | API key + device key)
- POST /check-trial-eligibility-batch — Check trial eligibility for multiple products (API key | API key + session | API key + device key)
- POST /check-upgrade-eligibility — Check upgrade eligibility and preview proration (API key | API key + session | API key + device key)
- POST /create-web-checkout — Start a Stripe web checkout (API key | API key + session | API key + device key)
- POST /get-customer-subscriptions — Retrieve a web buyer's purchases from a management link or checkout session (no key)
- POST /register-device-token — Bind an APNs / FCM push token to the proven customer (API key | API key + session | API key + device key)
- POST /unregister-device-token — Deactivate a push token in the key's project (API key)
- POST /check-pending-actions — Claim the journey actions queued for the caller (API key | API key + session | API key + device key)
- POST /complete-pending-action — Report the outcome of a queued journey action (API key | API key + session | API key + device key)
- POST /revoke-device-key — Kill a copied device key (project secret key only) (API key)
- POST /set-customer-attribution — Set attribution and campaign mapping details for a customer (API key | API key + session | API key + device key)
- POST /set-device-identifiers — Store advertising identifiers and tracking consent status (API key | API key + session | API key + device key)
- POST /upgrade-subscription — Change plan or upgrade a user subscription (API key)
- POST /user-properties — Apply atomic modifications to user profile properties (API key | API key + session | API key + device key)
- POST /virtual-currency — Virtual currency balances, transactions and adjustments (path-routed) (API key | API key + session | API key + device key)
- POST /redeem-with-currency — Spend virtual currency to grant a package's entitlements (API key | API key + session | API key + device key)
- POST /bdsurvey-fetch — Fetch survey config with eligibility targeting (API key | API key + session | API key + device key)
- POST /bdsurvey-submit — Record user survey response state (API key | API key + session | API key + device key)
- POST /bdsurvey-list — Retrieve active surveys mapping targeted users (API key | API key + session | API key + device key)
- POST /bdsurvey-manifest — Retrieve eligible survey IDs for client disk caching (API key | API key + session | API key + device key)
- POST /get-wall-for-placement — The one placement / offering delivery endpoint (hosted and headless) (API key | API key + session | API key + device key)
- POST /auth-account-delete — Erase the signed-in user's account (Apple 5.1.1(v) & GDPR) (API key + session)
- POST /check-user-access — Assess user access restriction status (API key | API key + session | API key + device key)
- POST /sync-subscriber — Set a customer's messaging channel preferences (and, server-side, contact profile) (API key | API key + session | API key + device key)
- POST /restrict-user-access — Restrict a customer's access (dashboard admin action) (dashboard session)
- POST /execute-paywall-action — Securely execute server-side tap actions (API key | API key + session | API key + device key)
- POST /feature-flags/evaluate — Evaluate active feature flags for a user (API key | API key + session | API key + device key)
- POST /record-external-event — Record non-revenue custom subscription state changes (API key)
- POST /record-external-purchase — Record a purchase from the merchant's server (API key)
- POST /record-session-replay — Ingest session replay events/attachments from clients (API key | API key + session | API key + device key)
- POST /track-paywall-action — Ingest status logs for paywall user interactions (API key | API key + session | API key + device key)
- POST /trigger-inapp-message — Check and track trigger states for in-app messaging (API key | API key + session | API key + device key)

### Removed endpoints (do not call)

- `fetch-offering` — use get-wall-for-placement with render_mode "headless"
- `fetch-offerings-for-placement` — use get-wall-for-placement with render_mode "headless"
- `get-placement-config` — use get-wall-for-placement
- `get-placement-offering` — use get-wall-for-placement with render_mode "headless"
- `get-placement-gates` — use get-wall-for-placement with render_mode "headless" (presentation.gated + presentation.required_entitlement)
- `create-app-to-web-checkout` — use create-web-checkout with source "app_to_web"
- `track` — use ingest-events

## Getting started

- [Code Examples](https://billdog.io/docs/code-examples.md): Tested BillDog snippets in several languages: initialise the SDK, fetch a paywall, handle purchase callbacks, check entitlements, track events, set user…
- [BillDog Glossary](https://billdog.io/docs/glossary.md): Definitions for the terms used across BillDog docs — paywalls and rendering, analytics, experimentation, engagement, environments and networking.
- [Quick Start Guide](https://billdog.io/docs/quickstart.md): Go from an empty project to a live BillDog paywall in about 15 minutes — create a project, install the SDK, define an offering and present your first paywall.
- [What SDK do I need?](https://billdog.io/docs/sdk-selection.md): Decide which BillDog SDK you need — the Full SDK for monetization plus engagement, or the Engagement SDK alone — based on your platform and what you're…
- [Troubleshooting Guide](https://billdog.io/docs/troubleshooting.md): Common BillDog issues by category, each with the symptom, likely cause and a step-by-step fix — including canonical PurchaseResult mapping and searchable…

## Guides

- [API Reference](https://billdog.io/docs/api-reference.md): BillDog REST API reference: authentication, customers, subscriptions, entitlements, paywalls, events and webhooks, with request and response examples. Auth…
- [App Review Request](https://billdog.io/docs/app-review-request.md): Trigger native in-app review prompts through BillDog on iOS and Android, including platform quotas, eligibility rules and how to avoid wasting a request.
- [Apple App Store Privacy Details](https://billdog.io/docs/apple-privacy.md): What to declare in App Store Connect privacy labels when using BillDog — disclosures by data type, optional IDFA and ad tracking, and in-code privacy controls.
- [Attribution Integrations](https://billdog.io/docs/attribution.md): Store identifiers from 20 attribution and analytics providers (Adjust, AppsFlyer, Branch, Firebase, Mixpanel, OneSignal, Airship, CleverTap, Iterable, Tenjin…
- [Audience Segmentation](https://billdog.io/docs/audience-segmentation.md): Build BillDog audiences from behaviour, properties and revenue state, then reuse the same segment across paywalls, messaging, surveys and experiments.
- [BillDog Auth](https://billdog.io/docs/auth.md): Sign-in, sessions and entitlements in one token. What BillDog Auth is, the two nouns you need, which platforms have it, and where to start.
- [Auth API Reference](https://billdog.io/docs/auth/api-reference.md): Every BillDog Auth endpoint: the base URL, how requests are authenticated, the response envelope, and the full operation table.
- [Auth Card Reference](https://billdog.io/docs/auth/auth-card-reference.md): Every property on the Auth Card, the five steps it moves through, what happens on each surface, and the localisation and error behaviour.
- [Building a Sign-In Wall](https://billdog.io/docs/auth/auth-walls.md): Author a hosted sign-in screen in the Paywall Builder: the four starting recipes, what the Auth Card owns, branding, where the wall is served and how a…
- [Auth Errors](https://billdog.io/docs/auth/errors.md): What each status and error code means, why every credential failure looks the same, and how to debug the ones that are genuinely ambiguous.
- [Hosted or SDK?](https://billdog.io/docs/auth/hosted-vs-native.md): Which way to sign people in on each platform, why a wall must not sign someone in inside a native app, and what to use instead.
- [Identities & Identifiers](https://billdog.io/docs/auth/identities.md): Email, phone and username sign-in, the identifier_kind parameter, verification, and how a signed-in user is linked to a BillDog customer.
- [JWT Templates](https://billdog.io/docs/auth/jwt-templates.md): Add your own claims to BillDog session tokens: creating a template, applying it, reserved claims, custom lifetimes, and the two ways to manage them.
- [Limits & Lifetimes](https://billdog.io/docs/auth/limits.md): Every number in BillDog Auth in one place: token and code lifetimes, rate-limit buckets, lockout, caps and payload ceilings — and which are configurable.
- [Multi-Factor Authentication](https://billdog.io/docs/auth/mfa.md): TOTP enrolment, backup codes, the project-wide MFA mandate, and the one rule that decides whether a wrong code is a retry or a lockout.
- [Migrating from Another Provider](https://billdog.io/docs/auth/migrating.md): Import users from Clerk, Auth0 or Firebase — how password hashes are carried over, who cannot sign in afterwards, and how to reach them.
- [Organizations](https://billdog.io/docs/auth/organizations.md): Teams, roles, invitations and verified domains — and how a member inherits the organization's entitlements through the active-organization claim.
- [Passkeys](https://billdog.io/docs/auth/passkeys.md): WebAuthn sign-in with Face ID, Touch ID or a security key: registering a passkey, signing in with one, and what each platform needs.
- [Passwordless — Email & SMS Codes](https://billdog.io/docs/auth/passwordless.md): One-time codes over email and SMS: requesting one, completing it, delivery, the dialling-code allowlist and the monthly spend cap.
- [Passwords](https://billdog.io/docs/auth/passwords.md): Password sign-in, the configurable policy, the breach check, how passwords are stored, and how a password is reset or changed from every SDK and from a hosted…
- [Auth Quickstart](https://billdog.io/docs/auth/quickstart.md): Sign a user in, hold the session across page loads, reset a password, and verify the token on your own backend — end to end, in about fifteen minutes.
- [SCIM Provisioning](https://billdog.io/docs/auth/scim.md): Sync users and groups from Okta or Entra ID: minting a provisioning token, the endpoints, deprovisioning semantics, and mapping directory groups to…
- [Security & Compliance](https://billdog.io/docs/auth/security.md): What BillDog Auth defends against and how — enumeration and timing equality, rate limits, reuse detection, credential storage, data residency and erasure.
- [Sessions & Tokens](https://billdog.io/docs/auth/sessions.md): The two tokens BillDog Auth issues, how long each lives, where to keep them, rotation with reuse detection, and how to end a session.
- [Google, Apple & Facebook Sign-In](https://billdog.io/docs/auth/social.md): Social sign-in two ways — the provider's own SDK, or a server-side PKCE redirect — plus provider setup, the Apple signing key, redirect allowlisting, second…
- [OIDC Single Sign-On](https://billdog.io/docs/auth/sso-oidc.md): Connect a custom OpenID Connect provider: discovery, the write-only client secret, domain routing, and how the callback is verified.
- [SAML Single Sign-On](https://billdog.io/docs/auth/sso-saml.md): Connect Okta, Entra ID or any SAML 2.0 IdP: the three strings your IdP needs, domain routing, SP- and IdP-initiated sign-in, and the one setting that must be…
- [Verifying Tokens on Your Server](https://billdog.io/docs/auth/verify-tokens.md): Offline signature verification against a cached JWKS, the environment check that is a security control, entitlement truncation, and when to reach for…
- [Auth Webhooks](https://billdog.io/docs/auth/webhooks.md): The thirteen user, session and organization events, what their payloads carry, how deliveries are signed, and how retries and auto-disable work.
- [Plans, Usage & Billing](https://billdog.io/docs/billing.md): How BillDog meters your account, what the free ceiling does to your SDK, and where the controls that actually change your bill live.
- [BillDog CLI](https://billdog.io/docs/cli.md): Reference for the BillDog CLI (@billdog.io/cli): detects your framework and installs the right SDK, plus commands, flags, diagnostic checks, code generators…
- [Retention Cohorts & Cohort Analysis](https://billdog.io/docs/cohorts.md): Build reusable saved audiences from event frequency and property predicates, then scope any analytics report — or a campaign — to them.
- [Compliance & Guidelines](https://billdog.io/docs/compliance.md): Compliance requirements for BillDog web checkout: Apple App Store and Google Play rules, GDPR obligations and payment regulations, with the next step for each.
- [Component Reference](https://billdog.io/docs/component-reference.md): Every BillDog paywall component by category — layout, text, media, buttons and inputs — with the properties, defaults and platform support for each one.
- [Creating Surveys](https://billdog.io/docs/creating-surveys.md): Build a survey in the BillDog builder: question types, branching conditions and the operators used to compare answers, from first draft through to publish.
- [Custom Purchases & Non-Store Products](https://billdog.io/docs/custom-purchases.md): Route purchases through your own billing stack (RevenueCat, Qonversion, raw StoreKit/Play Billing, Stripe, Paddle) using BillDog's PurchaseController and…
- [Subscription Management & Retention Flows](https://billdog.io/docs/customer-center.md): Build an in-app 'Manage subscription' screen with the Paywall Builder: open the store's subscription settings, restore purchases, request refunds on iOS…
- [Device Layouts](https://billdog.io/docs/device-layouts.md): Give one paywall a different layout for phones, large phones, tablets and desktop, in portrait and landscape — so the buy button stays on screen when the…
- [Engage SDK Guide](https://billdog.io/docs/engage-sdk-guide.md): Overview of the BillDog Engagement SDKs — analytics, surveys, messaging and feature flags — and which platform package to install for your stack.
- [Experiments & A/B Testing](https://billdog.io/docs/experiments.md): Run A/B tests on BillDog: flag and experiment types, reading a variant in-app, local vs server evaluation, targeting rules, and how assignments reach Analytics.
- [Feature Flags](https://billdog.io/docs/feature-flags.md): Ship code dark, target by audience, roll out by percentage, and deliver remote JSON config — with every verdict computed server-side.
- [Full SDK Guide](https://billdog.io/docs/full-sdk-guide.md): What the BillDog Full SDK includes — the monetization engine plus event tracking, messaging and surveys — and which platforms it supports in a single install.
- [Conversion Funnels & Drop-off Analysis](https://billdog.io/docs/funnels.md): Measure step-by-step conversion across up to eight events, and find exactly where users drop out.
- [Group Analytics](https://billdog.io/docs/group-analytics.md): Analyse B2B usage by company, workspace or team instead of by individual user — five custom group slots, plus a subscription cohort BillDog maintains for you.
- [Headless Paywalls (BYO-UI)](https://billdog.io/docs/headless-paywalls.md): Build your own paywall UI in SwiftUI, Jetpack Compose, React Native, Expo, Flutter, Web React, or any custom engine via REST API while BillDog resolves the…
- [Identifier Best Practices](https://billdog.io/docs/identifier-best-practices.md): Naming conventions and project scoping for BillDog: app user IDs, aliases, anonymous identity, environment separation, and identifiers you should never reuse.
- [Insights, Boards & Alerts](https://billdog.io/docs/insights-boards-alerts.md): Saving a report, assembling boards, alerting on a metric, and annotating a timeline — what carries across each step and what gets dropped.
- [Adjust attribution](https://billdog.io/docs/integrations/adjust.md): Store the Adjust identifier on the BillDog customer with setAdjustId (key adjustId). BillDog keeps it on the customer and doesn't send it to Adjust.
- [Airship ID](https://billdog.io/docs/integrations/airship.md): Store the Airship identifier on the BillDog customer with setAirshipChannelID (key airshipChannelId). BillDog keeps it on the customer and doesn't send it to…
- [AppsFlyer attribution](https://billdog.io/docs/integrations/appsflyer.md): Store the AppsFlyer identifier on the BillDog customer with setAppsflyerId (key appsflyerId). BillDog keeps it on the customer and doesn't send it to AppsFlyer.
- [Branch attribution](https://billdog.io/docs/integrations/branch.md): Store the Branch identifier on the BillDog customer with setBranchId (key branchId). BillDog keeps it on the customer and doesn't send it to Branch.
- [CleverTap ID](https://billdog.io/docs/integrations/clevertap.md): Store the CleverTap identifier on the BillDog customer with setCleverTapID (key cleverTapId). BillDog keeps it on the customer and doesn't send it to CleverTap.
- [Iterable ID](https://billdog.io/docs/integrations/iterable.md): Store the Iterable identifier on the BillDog customer with setIterableUserID (key iterableId). BillDog keeps it on the customer and doesn't send it to Iterable.
- [Kochava attribution](https://billdog.io/docs/integrations/kochava.md): Store the Kochava identifier on the BillDog customer with setKochavaDeviceID (key kochavaId). BillDog keeps it on the customer and doesn't send it to Kochava.
- [MoEngage ID](https://billdog.io/docs/integrations/moengage.md): Store the MoEngage identifier on the BillDog customer with setMoEngageAnonymousID (key moEngageAnonymousId). BillDog keeps it on the customer and doesn't send…
- [mParticle ID](https://billdog.io/docs/integrations/mparticle.md): Store the mParticle identifier on the BillDog customer with setMparticleID (key mparticleId). BillDog keeps it on the customer and doesn't send it to mParticle.
- [OneSignal ID](https://billdog.io/docs/integrations/onesignal.md): Store the OneSignal identifier on the BillDog customer with setOnesignalID (key onesignalId). BillDog keeps it on the customer and doesn't send it to OneSignal.
- [Singular attribution](https://billdog.io/docs/integrations/singular.md): Store the Singular identifier on the BillDog customer with setSingularInstallID (key singularId). BillDog keeps it on the customer and doesn't send it to…
- [Tenjin attribution](https://billdog.io/docs/integrations/tenjin.md): Store the Tenjin identifier on the BillDog customer with setTenjinAnalyticsInstallationID (key tenjinId). BillDog keeps it on the customer and doesn't send it…
- [Known Store Issues](https://billdog.io/docs/known-store-issues.md): Store-platform behaviours that are easy to mistake for SDK bugs — what the symptom looks like, why it happens, and how to confirm it before changing code.
- [Android release builds: no products, purchases do nothing](https://billdog.io/docs/known-store-issues/android-minification.md): R8 strips the Play Billing implementation, the SDK falls back to a no-op manager, and the paywall renders empty with no crash and no error. Debug builds are…
- [A consumable can only be bought once — Play says “already owned”](https://billdog.io/docs/known-store-issues/consumable-already-owned.md): BillDog decides consume-vs-acknowledge from the product type in your catalog, not from Play. A mis-typed product gets acknowledged, and Play then treats it as…
- [The Lexicon](https://billdog.io/docs/lexicon.md): Your event and property catalog: which parts of it govern what you can query, which parts are a private notebook, and why Data Drop and Permissions do not do…
- [LLM Observability](https://billdog.io/docs/llm-observability.md): Trace your model calls, manage prompt versions, and read the cost and latency numbers correctly.
- [MCP Server](https://billdog.io/docs/mcp-server.md): Connect your AI coding assistant (Claude Code, Cursor, Windsurf, Claude Desktop) to BillDog — diagnostic setup checklists, catalog and paywall inspection, and…
- [Messaging Channels](https://billdog.io/docs/messaging.md): Push, email, SMS, in-app and Live Activities: what each one needs, what its health badge and metrics actually mean, and which providers cannot send.
- [Messaging & Survey Analytics](https://billdog.io/docs/messaging-survey-analytics.md): The nine messaging reports and the six survey reports: one shared definition behind most of them, which rates only email can produce, and the three reports…
- [Trial Reminder Notifications](https://billdog.io/docs/notifications.md): Schedule trial reminder notifications in BillDog — delivery methods, configuration, platform-specific setup for iOS and Android, and the notification lifecycle.
- [Paywall Builder Guide](https://billdog.io/docs/paywall-builder.md): Use the BillDog paywall builder: the canvas and device preview, adding and arranging components, styling and theming, content and data binding, and media.
- [Paywall Display Settings](https://billdog.io/docs/paywall-display-settings.md): Choose how a paywall is presented in your app — full screen, sheet, popup, drawer or push — whether users can dismiss it, and game controller input.
- [Multi-Screen Funnels](https://billdog.io/docs/paywall-funnels.md): Build a paywall with several screens — onboarding, questions, offer — connect them in the Flow Graph, and route users with conditions and splits.
- [Paywall Localization](https://billdog.io/docs/paywall-localization.md): Translate paywalls into any locale from the builder — AI-assisted, with dynamic variables protected from the translator and rejected if mangled.
- [Preview & Publishing](https://billdog.io/docs/paywall-preview-publishing.md): Save drafts, fix validation issues, preview and share a paywall, publish and unpublish it, and restore earlier versions.
- [Paywall Settings, Products & Audience](https://billdog.io/docs/paywall-settings.md): The builder's Settings, Products, Audience and Notifications panels: the paywall identifier, intro and promotional offers, the offering it sells, and who is…
- [Using BillDog Paywalls alongside RevenueCat & Adapty](https://billdog.io/docs/paywalls-with-revenuecat-adapty.md): Show BillDog paywalls while RevenueCat or Adapty keeps making the purchase: a custom purchase controller in React Native, a purchase adapter on the web, and…
- [Placements Guide](https://billdog.io/docs/placements.md): Control which BillDog offering appears where using placements — named app locations you can retarget remotely without shipping a new build.
- [Predicted LTV](https://billdog.io/docs/predictions.md): Forecast cohort lifetime value at 30, 90 and 365 days from a fitted retention curve — with an honest confidence score and an explicit minimum-data threshold.
- [Product Analytics (Client SDKs)](https://billdog.io/docs/product-analytics.md): Capture product analytics from BillDog client SDKs: manual events, automatic tracking, error tracking, autocapture, and identifying users across devices.
- [Render Mode Guide](https://billdog.io/docs/render-modes.md): Choose the right render mode for your paywalls — native, WebView, or intelligent mode
- [Retention & Stickiness](https://billdog.io/docs/retention.md): See how many users come back after their first visit, and how often your monthly users show up on any given day.
- [Revenue & Subscription Metrics](https://billdog.io/docs/revenue-metrics.md): What each of the 21 revenue reports actually counts, what it leaves out, which of them are not populated, and why two reports of the same thing disagree.
- [Review Analytics](https://billdog.io/docs/review-analytics.md): Measure in-app review request performance in BillDog: prompt volume, acceptance rate, and which triggers and timings produce the most completed reviews.
- [Smart Review Timing](https://billdog.io/docs/review-timing.md): Time in-app review prompts using BillDog behaviour signals — after a success moment rather than at random — with rules, cooldowns and platform quota limits.
- [Self-Hosted Proxy](https://billdog.io/docs/self-hosted-proxy.md): Route BillDog SDK traffic through your own infrastructure for compliance, observability or regional failover using setProxyURL on iOS and Android.
- [Session Replay](https://billdog.io/docs/session-replay.md): Record and replay real user sessions on web, iOS and Android — with masking on by default and sampling that actually controls what you are billed.
- [Smart Paywall Caching](https://billdog.io/docs/smart-caching.md): How BillDog caches paywall configuration for instant display and offline rendering: cache layers, staleness limits, invalidation, and the telemetry it emits.
- [Survey Results & Analytics](https://billdog.io/docs/survey-results.md): Read BillDog survey results: the live KPI cards, per-question breakdowns, response filtering, and how answers flow back into analytics and audience targeting.
- [Survey Targeting & Display Conditions](https://billdog.io/docs/survey-targeting.md): Target BillDog surveys precisely: how eligibility is evaluated, URL and route rules, audience and property targeting, feature flags, sampling and show-once…
- [Surveys API & Presentation Guide](https://billdog.io/docs/surveys.md): Control BillDog surveys from code — presentation APIs, targeting variables, lifecycle callbacks, event trigger maps, native vs WebView rendering, offline…
- [Variable System Reference](https://billdog.io/docs/variable-system.md): BillDog's variable system — both interpolation syntaxes, the resolution priority chain, built-in variables, localizable text properties and key format rules.
- [Virtual Currencies Guide](https://billdog.io/docs/virtual-currencies.md): Build in-app economies with BillDog virtual currencies: setup, SDK integration, API reference, manual balance management, expiration rules and reporting.
- [Web Checkout Setup Guide](https://billdog.io/docs/web-checkout.md): Deep-link from iOS or Android into BillDog web checkout for reader apps and external purchase entitlement: enable it, wire Stripe webhooks, redeem purchases.
- [Web Analytics, Errors & Heatmaps](https://billdog.io/docs/web-errors-heatmaps.md): Three reports that only work once you turn capture on, what each number means, and how to tell sample data from your own.
- [Web Redemption Links](https://billdog.io/docs/web-redemption-links.md): Hand a web (Stripe) purchase over to your iOS or Android app with a single-use redemption token, delivered as a deep link, a QR code, or a copyable code.
- [Webhooks Reference](https://billdog.io/docs/webhooks.md): BillDog webhooks in both directions: incoming store notifications from Apple, Google and Stripe, and outgoing event dispatch to your endpoints — subscription…
- [WebView Preload Strategies](https://billdog.io/docs/webview-preload-strategies.md): Preload strategies for BillDog WebView paywalls — when each strategy warms up the WebView, and where to set it in the Paywall Builder.
- [xFlow Templating Reference](https://billdog.io/docs/xflow-reference.md): xFlow templating reference for BillDog: control-flow tags, operators and truthiness, the filter library, filter chaining and ms-string shorthand, with examples.

## Integrations

- [Adapty Integration](https://billdog.io/docs/adapty-integration.md): Adapty and BillDog today: import your Adapty data, or keep Adapty making purchases behind a BillDog paywall. A ready-made Adapty bridge is coming soon.
- [Airbridge Attribution Integration](https://billdog.io/docs/airbridge-integration.md): Store the Airbridge device UUID on the BillDog customer. BillDog doesn't send anything to Airbridge.
- [Amplitude Integration for Mobile Revenue](https://billdog.io/docs/amplitude-integration.md): Forward BillDog subscription events into Amplitude, keyed on your app user ID.
- [Analytics & Attribution Pipeline](https://billdog.io/docs/analytics-integration.md): How subscription and attribution data leaves BillDog today: server-side connectors, outgoing webhooks, and attribution identifiers stored on the customer.
- [Apple Search Ads](https://billdog.io/docs/apple-search-ads-integration.md): Record the Apple Search Ads campaign, ad group and keyword behind an install, using AdServices on iOS 14.3+.
- [Braze Integration for Lifecycle Messaging](https://billdog.io/docs/braze-integration.md): Send BillDog subscription lifecycle events to Braze server-to-server, matched to the Braze user whose external ID is your app user ID.
- [Meta Ads (Facebook)](https://billdog.io/docs/meta-ads-integration.md): Store the Facebook anonymous ID on the BillDog customer and record fbclid from Meta ad click-throughs. Sending conversions to Meta is coming soon.
- [Mixpanel Integration for Subscriptions](https://billdog.io/docs/mixpanel-integration.md): Forward BillDog subscription events into Mixpanel, keyed on your app user ID.
- [PostHog Integration for Subscriptions](https://billdog.io/docs/posthog-integration.md): Store the PostHog distinct ID on the BillDog customer. There is no PostHog connector yet: BillDog sends nothing to PostHog.
- [RevenueCat integration](https://billdog.io/docs/revenuecat-integration.md): Two paths for RevenueCat and BillDog: import your RevenueCat data into BillDog today, or (coming soon) keep RevenueCat making purchases while BillDog records…
- [Segment Integration & Event Forwarding](https://billdog.io/docs/segment-integration.md): Forward BillDog subscription events into Segment as track calls keyed on your app user ID.
- [SendGrid Integration for Email](https://billdog.io/docs/send-grid-integration.md): BillDog emails your customers through your SendGrid account when subscriptions start, trials are ending and payments fail.
- [Slack Integration & Revenue Alerts](https://billdog.io/docs/slack-integration.md): Post subscription events straight into a Slack channel — new subscriptions, renewals, churn and failed payments — with no code.
- [Stripe Integration Guide](https://billdog.io/docs/stripe-integration.md): Connect Stripe to BillDog for web checkout and subscriptions: API keys, webhook configuration, creating products, linking prices, and test vs live mode.
- [Superwall Integration](https://billdog.io/docs/superwall-integration.md): Present Superwall paywalls while BillDog buys, restores, validates receipts and owns entitlements.

## SDK guides

- [Android SDK Integration Guide](https://billdog.io/docs/android.md): Integrate the BillDog Android SDK in Kotlin — configure repositories and dependencies, initialise, manage customer identity, check entitlements and show…
- [Android Engagement SDK (BillDogEng)](https://billdog.io/docs/android-eng.md): Install and initialise the BillDog Android Engagement SDK in Kotlin: automatic event tracking, screen views, identity, in-app surveys and remote feature flags.
- [Capacitor SDK (Coming Soon)](https://billdog.io/docs/capacitor.md): The BillDog Capacitor SDK is in our pipeline and not yet supported. What is planned, what an Ionic Capacitor app can use today, and how to join the waitlist.
- [Capacitor Engagement SDK (Coming Soon)](https://billdog.io/docs/capacitor-eng.md): A BillDog engagement plugin for Capacitor is not available yet. What an Ionic Capacitor app can use today for analytics and surveys, and how to join the…
- [Cordova SDK (Coming Soon)](https://billdog.io/docs/cordova.md): The BillDog Cordova plugin is in our pipeline and not yet published. What is planned, what a Cordova or PhoneGap app can use today, and how to join the…
- [Expo SDK Guide](https://billdog.io/docs/expo.md): Integrate BillDog in an Expo app: install the config plugin, configure the SDK, identify customers, present paywalls and check entitlements.
- [Flutter SDK Guide](https://billdog.io/docs/flutter.md): Integrate the BillDog Flutter SDK: install, raise the iOS deployment target and Android minSdk, configure, identify customers, present paywalls and check…
- [iOS SDK Integration Guide](https://billdog.io/docs/ios.md): Integrate the BillDog iOS SDK in Swift: installation, initialisation, customer identity, entitlement checks, presenting paywalls and restoring purchases.
- [iOS Engagement SDK (BillDogEng)](https://billdog.io/docs/ios-eng.md): Install and initialise the BillDog iOS Engagement SDK in Swift: behaviour capture, deep links, auto-tracking, session replay, identity, surveys and feature…
- [Kotlin Multiplatform SDK (Coming Soon)](https://billdog.io/docs/kotlin-multiplatform.md): The BillDog Kotlin Multiplatform SDK is in our pipeline and not yet published. What a KMP project can use today, and how to join the waitlist.
- [React Native SDK Guide](https://billdog.io/docs/react-native.md): Integrate the BillDog React Native SDK: install and configure, identify customers, present paywalls and check entitlements.
- [Roku SDK (Coming Soon)](https://billdog.io/docs/roku.md): The BillDog Roku SDK and Roku Pay support are in our pipeline and not yet available. What is planned, what a Roku channel can use today, and how to join the…
- [Server-Side SDKs (BillDogEng)](https://billdog.io/docs/server-sdk.md): BillDog server SDKs across nine languages: event capture, super properties, group and alias mapping, local feature-flag evaluation and the survey data API.
- [Unity SDK (Coming Soon)](https://billdog.io/docs/unity.md): The BillDog Unity SDK is in our pipeline and not yet published. What is planned, what Unity games can use today through the REST API, and how to join the…
- [Unity Engagement SDK (Coming Soon)](https://billdog.io/docs/unity-eng.md): The BillDog Unity Engagement SDK is in our pipeline and not yet published. What is planned, what Unity games can use today for analytics, and how to join the…
- [Web SDK Guide](https://billdog.io/docs/web.md): Integrate BillDog into a web app with TypeScript or JavaScript: install, configure, present paywalls via placements, and restore purchases.

## Store setup

- [Amazon Appstore Setup (Coming Soon)](https://billdog.io/docs/amazon-appstore-setup.md): Amazon Appstore purchase tracking is not supported in BillDog yet. There is nothing to configure today; this page explains what that means for your app.
- [Apple App Store Setup](https://billdog.io/docs/app-store-setup.md): Connect App Store Connect to BillDog: In-App Purchase key, app identifiers, product sync, App Store Server Notifications and sandbox testing for iOS…
- [Google Play Store Setup](https://billdog.io/docs/play-store-setup.md): Connect Google Play Console to BillDog: service account credentials, real-time developer notifications, product setup and testing Play Billing subscriptions.
- [Roku Channel Store Setup (Coming Soon)](https://billdog.io/docs/roku-setup.md): Planned Roku Channel Store setup for BillDog. Roku Pay purchases are not supported yet; this page describes the setup that is coming.
- [Virtual Currencies Setup Guide](https://billdog.io/docs/virtual-currencies-setup.md): Set up BillDog virtual currencies — prerequisites, the two scheduled edge functions, configuring cron jobs and expiration settings, and how balances are…