# Paywalls.ai Documentation

## Docs

- [Chat completion](https://docs.paywalls.ai/api-reference/chat/completions/post.md): This endpoint proxies an OpenAI-compatible chat completion request and charges the user based on the configured monetization model (per request, per token, etc).
- [Introduction](https://docs.paywalls.ai/api-reference/introduction.md): Here you’ll find detailed information on every endpoint, including request parameters, response formats, and examples.
- [Models](https://docs.paywalls.ai/api-reference/models/get.md): Lists all models available through the proxy, including pricing information per model.
- [Deposit credits](https://docs.paywalls.ai/api-reference/user/balance/deposit/post.md): This endpoint allows you to deposit credits into a user's virtual balance. This is only applicable if the paywall is configured in "default" mode. Deposits will increase the user's balance, allowing them to make requests against the paywall.
- [Get user balance](https://docs.paywalls.ai/api-reference/user/balance/get.md): Returns the current prepaid balance for the user, both in raw units and a formatted string.
- [Top up balance](https://docs.paywalls.ai/api-reference/user/balance/topup/get.md): Returns a link the user can visit to top up their balance.
- [Charge user](https://docs.paywalls.ai/api-reference/user/charge/post.md): Charges a specific user an arbitrary amount (in USDC equivalent), if the user is connected and has sufficient balance.
- [Authorize user](https://docs.paywalls.ai/api-reference/user/connect/get.md): Checks whether a user is currently connected (i.e., has authorized charging).
- [Disconnect user](https://docs.paywalls.ai/api-reference/user/disconnect/get.md): Revokes the user’s charging authorization and disconnects them from the paywall.
- [Paywall archived](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-archived.md): Triggered when a paywall is moved to the archived state.  Signals that traffic should be shut down or hidden because the paywall transitioned into an archived state.  **Payload fields**: `paywallId`, `ownerUserId`, `reason`.
- [Authorization completed](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-authorization-completed.md): Triggered when a user successfully connects to your paywall.  Confirms a user granted permissions so downstream systems can unlock premium features.  **Payload fields**: `paywallId`, `ownerUserId`, `externalUserId`, `walletUserId`, `connectionId`.
- [Authorization declined](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-authorization-declined.md): Triggered when a user declines an authorization request.  Surfaces a declined approval so customer success teams can follow up or adjust onboarding.  **Payload fields**: `paywallId`, `ownerUserId`, `externalUserId`, `walletUserId`, `requestId`, `reason`.
- [Authorization requested](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-authorization-requested.md): Triggered when a user approval request is created for your paywall.  Signals that a user needs to approve access, allowing apps to surface a relevant call-to-action.  **Payload fields**: `paywallId`, `ownerUserId`, `externalUserId`, `walletUserId`, `requestId`, `approvalUrl`, `mode`.
- [Authorization revoked](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-authorization-revoked.md): Triggered when an existing user connection is removed from your paywall.  Notifies consumers that a previously authorized user should no longer be charged.  **Payload fields**: `paywallId`, `ownerUserId`, `externalUserId`, `walletUserId`.
- [Manual charge completed](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-balance-charge-completed.md): Triggered when a pending manual charge is marked as settled.  Signals that a previously pending manual charge fully settled.  **Payload fields**: `paywallId`, `ownerUserId`, `walletUserId`, `activityId`, `settlementReference`.
- [Manual charge created](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-balance-charge-created.md): Triggered when a manual charge is recorded against a user's balance.  Exposes new manual debits, enabling real-time billing dashboards.  **Payload fields**: `paywallId`, `ownerUserId`, `walletUserId`, `activityId`, `amount`, `processingFeeAmount`.
- [Manual charge failed](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-balance-charge-failed.md): Triggered when a manual charge attempt fails.  Highlights manual charge failures so operators can investigate and retry if needed.  **Payload fields**: `paywallId`, `ownerUserId`, `walletUserId`, `activityId`, `amount`, `errorCode`.
- [Balance depleted](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-balance-depleted.md): Triggered when a charge finds the user's balance insufficient.  Helps trigger proactive outreach when a user attempts a charge with insufficient funds.  **Payload fields**: `paywallId`, `ownerUserId`, `walletUserId`, `requestedAmount`, `availableBalance`.
- [Balance deposit recorded](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-balance-deposit-created.md): Triggered when funds are deposited into a user's paywall balance.  Allows finance and analytics tools to reconcile when a user balance increases.  **Payload fields**: `paywallId`, `ownerUserId`, `walletUserId`, `externalUserId`, `amount`, `currency`, `source`, `activityId`.
- [Top-up link created](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-balance-topup-link-created.md): Triggered when a top-up checkout link is generated for a user.  Emitted whenever a reusable link is generated so client apps can share the URL with end users.  **Payload fields**: `paywallId`, `ownerUserId`, `walletUserId`, `redirectUrl`, `checkoutSessionId`.
- [Trial credits granted](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-balance-trial-granted.md): Triggered when trial credits are granted to a user.  Tracks complimentary credits so marketing and growth tooling maintain accurate lifetime value calculations.  **Payload fields**: `paywallId`, `ownerUserId`, `walletUserId`, `credits`, `activityId`.
- [Integration connected](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-integration-connected.md): Triggered when an integration is switched on for a paywall.  Broadcasts that a third-party integration is now active so provisioning hooks can run.  **Payload fields**: `paywallId`, `ownerUserId`, `integrationKey`, `enabledBy`.
- [Integration disconnected](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-integration-disconnected.md): Triggered when an integration is switched off for a paywall.  Lets dependants know an integration was turned off and follow-up cleanup may be required.  **Payload fields**: `paywallId`, `ownerUserId`, `integrationKey`, `disabledBy`.
- [Stripe webhook rotated](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-integration-stripe-webhook-rotated.md): Triggered when a new Stripe webhook endpoint is created for a paywall.  Keeps billing operators in sync when Stripe webhook endpoints are recreated or rotated.  **Payload fields**: `paywallId`, `ownerUserId`, `webhookId`, `url`, `secretSuffix`.
- [Proxy request blocked](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-proxy-request-blocked.md): Triggered when the proxy blocks a request during routing.  Highlights enforcement decisions made inside the proxy pipeline.  **Payload fields**: `paywallId`, `ownerUserId`, `requestId`, `walletUserId`, `reason`.
- [Proxy request canceled](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-proxy-request-canceled.md): Triggered when a proxied request is canceled before completion.  Shows when a proxied request was aborted before completion.  **Payload fields**: `paywallId`, `ownerUserId`, `requestId`, `walletUserId`, `model`.
- [Proxy request completed](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-proxy-request-completed.md): Triggered when the proxy finishes handling a request successfully.  Indicates the proxied request finished successfully.  **Payload fields**: `paywallId`, `ownerUserId`, `requestId`, `walletUserId`, `model`.
- [Proxy request failed](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-proxy-request-failed.md): Triggered when the proxy encounters an error processing a request.  Captures failures for alerting and debugging within the proxy pipeline.  **Payload fields**: `paywallId`, `ownerUserId`, `requestId`, `walletUserId`, `model`, `errorCode`.
- [Proxy request started](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-proxy-request-started.md): Triggered when the proxy receives a new request.  Marks the beginning of a proxied LLM request for tracing and latency analysis.  **Payload fields**: `paywallId`, `ownerUserId`, `requestId`, `walletUserId`, `model`.
- [Request blocked](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-request-blocked.md): Triggered when a paywall request is blocked before reaching the provider.  Communicates high-level block reasons (authorization, balance, policy) to client applications.  **Payload fields**: `paywallId`, `ownerUserId`, `walletUserId`, `reason`, `requestId`.
- [Paywall secret rotated](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-secret-rotated.md): Triggered when the API secret for a paywall is regenerated.  Enables credential stores to roll keys after a paywall secret was regenerated.  **Payload fields**: `paywallId`, `ownerUserId`, `secretLastFour`, `actorId`, `actorType`.
- [Stripe checkout completed](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-stripe-checkout-session-completed.md): Triggered when a Stripe Checkout session for a paywall user succeeds.  Helps reconcile Stripe settlements with internal balances.  **Payload fields**: `paywallId`, `ownerUserId`, `checkoutSessionId`, `amount`, `currency`, `walletUserId`.
- [Paywall updated](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-updated.md): Triggered whenever a paywall's settings are changed.  Provides a compact diff summary so audit and notification systems know which parts of the configuration moved.  **Payload fields**: `paywallId`, `ownerUserId`, `changedFields`, `summarySections`.
- [Usage charge created](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-usage-charge-created.md): Triggered when usage data creates a metered charge.  Feeds usage-based billing metrics with token counts and resulting cost.  **Payload fields**: `paywallId`, `ownerUserId`, `walletUserId`, `activityId`, `model`, `promptTokens`, `completionTokens`, `cost`.
- [Usage charge deferred](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-usage-charge-deferred.md): Triggered when a streaming request defers its usage charge.  Marks a streaming request whose charge will be computed later once usage statistics arrive.  **Payload fields**: `paywallId`, `ownerUserId`, `deferredRequestId`, `model`.
- [Usage rate limited](https://docs.paywalls.ai/api-reference/webhooks/events/paywall-usage-rate-limited.md): Triggered when a request hits the usage rate limit.  Notifies when a request is rate-limited so teams can monitor free-tier consumption.  **Payload fields**: `paywallId`, `ownerUserId`, `limit`, `date`, `model`, `walletUserId`.
- [Get delivery logs](https://docs.paywalls.ai/api-reference/webhooks/logs/get.md): Returns recent webhook delivery attempts for the authenticated paywall. Filter by subscription, status, event type, or adjust the number of records returned.
- [Delete a subscription](https://docs.paywalls.ai/api-reference/webhooks/subscriptions/[subscriptionId]/delete.md): Marks the subscription as inactive to stop future deliveries.
- [Get a subscription](https://docs.paywalls.ai/api-reference/webhooks/subscriptions/[subscriptionId]/get.md): Returns the latest configuration for the specified subscription.
- [List subscriptions](https://docs.paywalls.ai/api-reference/webhooks/subscriptions/get.md): Returns every webhook subscription configured for the authenticated paywall. Filter by active status with the `status` query parameter.
- [Subscribe to events](https://docs.paywalls.ai/api-reference/webhooks/subscriptions/post.md): Registers a new webhook endpoint for the authenticated paywall. Provide an HTTPS URL and one or more event types (or `*` for all events). The full signing secret is returned only once at creation time.
- [Model providers](https://docs.paywalls.ai/core-concepts/model-providers.md)
- [Paywalls, Wallets & Ledger](https://docs.paywalls.ai/core-concepts/paywalls-wallets-ledger.md)
- [Pricing & Metering](https://docs.paywalls.ai/core-concepts/pricing-metering.md)
- [Proxy](https://docs.paywalls.ai/core-concepts/proxy.md)
- [User Identity](https://docs.paywalls.ai/core-concepts/user-identity.md): To process billing and enforce access control, every request to Paywalls.ai must include a user identity.
- [BYOK vs Built-in Provider](https://docs.paywalls.ai/how-to-guides/byok-vs-built-in-provider.md)
- [Choose a mode (Default vs Shared)](https://docs.paywalls.ai/how-to-guides/choose-a-mode.md)
- [Configure Billing](https://docs.paywalls.ai/how-to-guides/configure-billing.md)
- [Configure paywall profile (Shared mode)](https://docs.paywalls.ai/how-to-guides/configure-profile.md)
- [Connect Stripe](https://docs.paywalls.ai/how-to-guides/connect-stripe.md)
- [Grant credits (Default mode)](https://docs.paywalls.ai/how-to-guides/grant-credits.md)
- [Monetize MCP Tools](https://docs.paywalls.ai/how-to-guides/monetize-mcp-tools.md)
- [No-code: Zapier, n8n, and other flows](https://docs.paywalls.ai/how-to-guides/no-code-zapier-n8n-flows.md)
- [Pass user ID](https://docs.paywalls.ai/how-to-guides/pass-user-id.md): How to include user identity in requests to Paywalls.ai.
- [Configure Proxy responses](https://docs.paywalls.ai/how-to-guides/proxy-responses.md)
- [Shared Mode](https://docs.paywalls.ai/how-to-guides/shared-mode.md)
- [Use case (monetization) recipes](https://docs.paywalls.ai/how-to-guides/use-case-monetization-recipes.md)
- [Use paywalls with existing subscriptions (Stripe, etc.)](https://docs.paywalls.ai/how-to-guides/use-paywalls-with-existing-subscriptions.md)
- [Use Paywalls with FlowXO](https://docs.paywalls.ai/how-to-guides/use-paywalls-with-flowxo.md): FlowXO Integration Step-by-Step
- [Use Paywalls with Open WebUI](https://docs.paywalls.ai/how-to-guides/use-paywalls-with-openwebui.md): Enable usage-based monetization for your Open WebUI deployment using Paywalls.
- [Webhooks Guide](https://docs.paywalls.ai/how-to-guides/webhooks.md): Use Paywalls webhooks to receive real-time notifications about important events.
- [Introduction](https://docs.paywalls.ai/index.md): Paywalls.ai is an AI‑first monetization platform for no‑code builders and developers alike.
- [Analytics & Reporting](https://docs.paywalls.ai/more/analytics-reporting.md)
- [Changelog](https://docs.paywalls.ai/more/changelog.md)
- [Errors, Limits & Reliability](https://docs.paywalls.ai/more/errors-limits-reliability.md)
- [Glossary](https://docs.paywalls.ai/more/glossary.md)
- [Playground](https://docs.paywalls.ai/more/playground.md)
- [Roadmap](https://docs.paywalls.ai/more/roadmap.md)
- [Security & Compliance](https://docs.paywalls.ai/more/security-compliance.md)
- [Test keys & Environments](https://docs.paywalls.ai/more/test-keys-and-environments.md)
- [Quickstart](https://docs.paywalls.ai/quickstart.md)
- [AI SDKs](https://docs.paywalls.ai/sdk-integrations/client-sdks.md)
- [Front-end Widgets](https://docs.paywalls.ai/sdk-integrations/front-end-widgets.md)
- [Google ADK](https://docs.paywalls.ai/sdk-integrations/google-adk.md)
- [PostHog integration](https://docs.paywalls.ai/sdk-integrations/posthog-llm-analytics.md)

## OpenAPI Specs

- [openapi](https://docs.paywalls.ai/api-reference/openapi.json)

## Optional

- [Website](https://paywalls.ai)
- [Dashboard](https://dashboard.paywalls.ai)