Server client

Current exports and methods

• setupPayment({ customerId, requestId, currency, makeDefault })

  Permissionsbilling:write

  Create a standalone card setup, without a subscription, entitlement or usage billing consent.

  Returns { setup }

• readPaymentSetup({ customerId, setupId })

  Permissionsbilling:read

  Verify the actual provider result of the original setup without duplicate charges.

  Returns { setup }

• listSubscriptions({ customerId?, entityId?, productId?, provider?, status?, cursor?, limit? })

  Permissionsbilling:read

  Page subscriptions by provider and cursor, retaining each provider contract.

  Returns { subscriptions }

• listPurchases({ customerId?, entityId?, productId?, provider?, status?, cursor?, limit? })

  Permissionsbilling:read

  Read verified purchase history and original amounts; history does not imply current entitlement.

  Returns { purchases }

• listSubscriptionConflicts({ customerId?, status?, cursor?, limit? })

  Permissionsbilling:read

  Read verified purchase conflicts and the memberships blocking an exclusive main plan.

  Returns { conflicts }

• retrySubscriptionConflict({ customerId, orderId })

  Permissionsbilling:write

  Retry the original delivery, returning blocked if blockers remain, without another payment.

  Returns { resolution }

• manageSubscriptionTrial({ customerId, requestId, action, reason, ...trialParameters })

  Permissionsbilling:write

  Start, extend or end a trial; store sources return instructions rather than a fabricated change.

  Returns { trial }

• readSubscriptionTrial({ customerId, operationId })

  Permissionsbilling:read

  Recover the original trial operation, reconciling Stripe when needed and retaining activation evidence.

  Returns { trial }

• previewSubscriptionBatch({ customerId, requestId, targets })

  Permissionsbilling:write

  Quote by actual provider container; continue with the original request while ready is false.

  Returns { batch }

• confirmSubscriptionBatch({ customerId, batchId })

  Permissionsbilling:write

  Accept frozen targets, retaining successful groups and recovering unfinished ones; partial is not complete.

  Returns { batch }

• readSubscriptionBatch({ customerId, batchId })

  Permissionsbilling:read

  Read each original group state without accepting a quote or issuing another provider operation.

  Returns { batch }

• abandonSubscriptionBatch({ customerId, batchId })

  Permissionsbilling:write

  Abandon only an unaccepted batch; submitted provider operations retain their original recovery tasks.

  Returns { batch }

• verifySubscriptions({ customerId })

  Permissionsbilling:read

  Compare the customer's contracts with Stripe Sandbox within the current App and environment. Returns consistency, drift or incomplete evidence without charging, repairing or refreshing the ledger.

  Returns { verification }

• previewRefund({ customerId, requestId, membershipId, purchaseId, lines, entitlementAction })

  Permissionsbilling:read

  Freeze a refund quote and entitlement treatment against the original purchase and invoice items.

  Returns { quote }

• refund({ customerId, operationId })

  Permissionsbilling:write

  Confirm the original refund operation; retries recover its existing provider attempt.

  Returns { operation }

• readRefund({ customerId, operationId })

  Permissionsbilling:read

  Read and recover an existing refund without creating another provider refund.

  Returns { operation }

• readBillingInvoice({ customerId, invoiceId, after, limit })

  Permissionsbilling:read

  Page through all verified invoice items with nextCursor, without charging.

  Returns { detail }

• readCreditStatement({ customerId, from, to, entityId?, snapshotAt, after, limit })

  Permissionscredits:read

  Up to 366 days. The first page uses null snapshotAt/after; subsequent pages retain the original snapshot and complete cursor.

  Returns { statement }

• previewUpdate({ customerId, requestId, membershipId, timing, change })

  Permissionsbilling:read

  Fix a plan or seat quote for an explicit membership while retaining sibling plans in the subscription.

  Returns { quote }

• update({ customerId, operationId })

  Permissionsbilling:write

  Confirm the fixed quote and recover its original charge attempt; verified payment determines fulfillment.

  Returns { operation }

• readSubscriptionUpdate({ customerId, operationId })

  Permissionsbilling:read

  Read the update status; pending payment, scheduled and effective results retain the original operation identity.

  Returns { operation }

• manageBalanceGrant({ customerId, command })

  Permissionscredits:manage

  Create recurring or one-time grants, adjust remaining balances, change expiry or revoke a rule with requestId and revision. Requires server credits:manage; payment facts remain immutable.

  Returns { grant }

• listBalanceGrants({ customerId, after, limit })

  Permissionscredits:read

  Read customer and Entity grants with available, held and spent balances. Page with nextCursor and a maximum limit of 100.

  Returns { grants }

• previewAttach({ customerId, entityId?, requestId, plans, provider, currency, offerId? })

  Permissionsbilling:read

  Save a fixed quote for an explicit customer without initiating payment; reuse requestId on retries. Independent execution supports one Stripe or free plan, or multiple paid Stripe plans on one connection, currency and billing interval, without multi-plan trials or seats.

  Returns { quote }

• attach({ customerId, operationId })

  Permissionsbilling:write

  Confirm after the customer reviews and accepts the quote. Retries reuse operationId and the original order without a Funnel.

  Returns { operation }

• restoreNativePurchase({ customerId, requestId, provider, purchaseIntentId, productId, signedTransaction?, purchaseToken? })

  Permissionsbilling:write

  Recover the same purchase and delivery from verified store facts without issuing credits twice.

  Returns { restore }

• readAiPricing({ entitlementId })

  Permissionscredits:read

  Read current model prices and markups.

  Returns { configuration }

• readBalanceSource({ customerId, sourceId })

  Permissionscredits:read

  Read available, held and spent funds in the plan's current window.

  Returns { balance }

• adjustBalance({ customerId, command })

  Permissionscredits:manage

  Add, subtract or set plan funds after checking expectedAvailable; retry the same requestId.

  Returns { balance }

• readUsage({ customerId, query })

  Permissionscredits:read

  Read capacity and actual non-consumable usage.

  Returns { usage }

• setUsage({ customerId, command })

  Permissionscredits:manage

  Atomically synchronize actual usage with expectedRevision, including decreases and usage above capacity.

  Returns { usage }

• readSubscriptionOperation({ customerId, operationId })

  Permissionsbilling:read

  Recover payment and delivery for an accepted operation without creating another provider attempt.

  Returns { operation }

• manageBillingLimits({ customerId, command })

  Permissionsbilling:write

  The trusted server sets customer or Entity usage limits, alerts or control: overage policies with the current revision and requestId. Overage policies contain allowed, overageLimit, skipOverageBilling and a UTC window. Entity policies override customer policies; removal restores inheritance. Customers still confirm payment consent.

  Returns { controls }

• getOrCreateCustomer(input)

  Permissionscustomers:write

  Find or create a customer by the host-verified externalUserId. Retries do not overwrite existing profiles; email is not identity. The optional fingerprint is a host-collected device identifier; only an environment-scoped hash is kept and the first recorded device is never replaced. You can also reserve a customer with only an email (for example, a contract signed before sign-up). When that user signs up, calling with an externalUserId and the same email claims the reservation in place, keeping its plans and balances. Only send verified emails; otherwise someone else could claim the reservation.

  Returns { customer, created }

• getCustomer({ lookup }) / listCustomers(filters)

  Permissionscustomers:read

  Look up an explicit id or externalUserId; listing applies current customer filters before pagination.

  Returns Customer response

• updateCustomer({ lookup, revision, requestId, patch })

  Permissionscustomers:write

  Update supplied profile fields and attributes. Use removeAttributes to delete keys and tagChanges for tags. Retain the revision and original requestId; reload after a conflict.

  Returns Customer response

• createCustomerSession(customerId)

  Permissionssessions:create

  Issue a short-lived session for the Indiana customer mapped to the host's verified login. Do not derive identity from browser parameters.

  Returns { customerToken, expiresAt }

• renewCustomerSession(input) / revokeCustomerSessions(input)

  Permissionssessions:create

  Recheck host authentication before renewal or revocation. Revocation requires sessions:create; reset clears SDK memory only.

  Returns Session response

• createGuestToken()

  Generate a guest proof on your backend, retain it in an HttpOnly cookie and reuse it for creation retries.

  Returns gg_gc_ token

• createGuestCustomer(input) / resumeGuestSession(input) / claimGuestCustomer(input)

  Permissionssessions:create

  Guest creation, recovery and claiming require their respective session or customers:write permissions. Derive the claimed externalUserId from verified login; authenticate before store purchases. Guest creation accepts a fingerprint; a merge keeps the existing customer's device and only adopts the guest's when none is recorded.

  Returns Guest/session response

• checkEntitlement({ customerId, requirement, commerce?, paywallId? })

  Permissionsentitlements:read

  Later source entry, absent from the published npm 0.0.1 artifact; requires a matching SDK build/release and server deployment. Check access and recommend products without consumption or automatic payment. Derive customerId from verified host authentication.

  Returns { check }

• readHoldings({ customerId })

  Permissionsentitlements:read

  Read current memberships and balances. Decimal quantities remain strings and existing memberships retain their contract versions.

  Returns { holdings }

• readLedger({ customerId, query })

  Permissionscredits:read

  Filter all history before pagination. Preserve the entire nextCursor and clear it when filters change.

  Returns { ledger }

• quoteBalance({ customerId, command })

  Permissionscredits:read

  command.operation is quote. A quote does not spend funds or replace atomic consumption.

  Returns { quote }

• mutateBalance({ customerId, command })

  Permissionscredits:consume

  Consume, reserve, confirm, release or refund at the original rate. Retain each action's original idempotencyKey and input; refunds also require credits:manage.

  Returns { receipt }

• readSeats(input) / manageSeat(input)

  Permissionscustomers:read

  Read purchased capacity and assign identified members. Assignments require billing:write; billed capacity changes are confirmed through Funnel nodes.

  Returns Seat response

• manageUsageEntity(input) / readCreditAnalytics(input) / readUsageAnalytics(input)

  Permissionscredits:manage

  Manage usage scope for a verified customer. Analytics requires credits:read; client-supplied payer identity does not authorize access.

  Returns Usage entity / analytics response

• submitUsageBatch(input) / readUsageBatch(input)

  Permissionscredits:consume

  Persist processing with an independent idempotent receipt per item. Reading progress requires credits:read.

  Returns Batch response

• grantOffer({ customerId, couponId, requestId })

  Permissionsoffers:grant

  Grant an offer from the trusted backend. The server checks scope, rules and inventory; retries reuse requestId. UI claims use a Funnel claim_offer action node.

  Returns Offer response

AI model pricing

• createConfiguredAiPricing(client, { entitlementId })

  Permissionscredits:read

  Read current model prices and markups for the App/environment. Recreate pricing after saving configuration; saved quotes are not repriced. See the AI token guide for integration and recovery.

  Returns Promise<AI pricing helper>

• createOpenRouterUsageClient({ openRouter, pricing, client, reasoning, context, persist, mapTokens? }) / trackOpenRouterUsage(input)

  Import from the separate /openrouter entry and install @openrouter/sdk in the host. Wrap chat.send, persisting actual usage and the frozen quote before atomic settlement. Recover with the original generationId, usage, quote and idempotency key without rerunning the model.

  Returns OpenRouter client / persisted usage record

• createAiUsageMiddleware({ pricing, client, modelId, reasoning, context, persist, mapTokens? })

  AI SDK v7 captures final usage for generate and streaming. context supplies a durable unique key per provider call or tool step; persist saves actual usage and the frozen quote before balance consumption. Interrupted usage is not estimated. Settlement failure is explicit; retry the original quote without rerunning the model.

  Returns LanguageModelV4Middleware

• createAiPricing(options?)

  Trusted server only. Read current model prices from Models.dev with a 15-minute cache. Configure default, provider and model markups or custom model prices. The metered entitlement must use one micro USD; a fixed credit rate converts the cost.

  Returns AI pricing helper

• pricing.quoteTokens({ modelId, tokens })

  Supply seven mutually exclusive token pools, using zero for unused pools. Freeze rates, context tier, markup, quantity and hash. Missing required prices are rejected. Explicit free prices retain real tokens in zero-cost events. Persist the original quote for job retries.

  Returns Promise<AiTokenQuote>

• pricing.trackTokens(client, { customerId, entitlementId, entityId?, idempotencyKey, quote, properties? })

  Permissionscredits:consume

  Validate the frozen quote and record tokens and model rates in one atomic balance mutation. Reuse the quote and idempotency key for retries; refunds use the original consumption price. Supply actual usage manually or capture it with createAiUsageMiddleware.

  Returns Promise<Balance mutation response>

• pricing.refreshPrices()

  Clear the price cache so the next quote reloads prices. Saved quotes, consumption and refunds retain their original rates.

  Returns void

• aiTokenQuoteSchema.parse(value) / aiPriceSnapshotSchema.parse(value)

  Validate a persisted current quote or price snapshot without calling a model or changing a balance.

  Returns Validated quote / price snapshot

Funnel and store recovery

• createFunnelDecisionClient(options).submit(input) / decide(input) / read(decisionId) / reportUsed(input)

  Trusted backend with sessions:create and funnels:run. Fix customer, Funnel and original requestId. submit returns without waiting; decide waits up to 30 seconds. Retry original input when acceptance is unknown; read the original decisionId when accepted but pending. reportUsed records a caller report without issuing or charging.

  Returns Decision status / decision / usage report

• createFunnelOrchestrationClient(options).signal(input) / readResults(runId)

  Backend sessions:create and funnels:run only. Send declared custom receipts, retaining eventId and data for retries. Acknowledgement is not consumption. Read completed task and consumed receipt results; custom receipts cannot confirm payment.

  Returns Receipt acknowledgement / node results

• renewFunnelRun(options, { runId, customerId })

  A backend with sessions:create and funnels:run renews the credential for the same identified customer without extending runExpiresAt. Browsers cannot renew it or change customer identity.

  Returns Renewed run credential

• createPaywallStartClient(options).start({ paywallId, requirement?, ...input })

  Later source entry, absent from the published npm 0.0.1 exports. With matching SDK/server versions, persist original input and requestId on the backend with a customer session and explicit provider/currency. requirement is frozen for the run while retaining the authored Paywall version.

  Returns FunnelRuntimeResponse

• createFunnelStartClient(options).start(input)

  Persist the original start input and requestId on the backend. source selects a Funnel, Paywall or published trigger. Requires sessions:create and funnels:run.

  Returns FunnelRuntimeResponse

• createNativeReceiptClient(options).recover(command)

  Current orders only: native_receipt uses a backend key plus the current customer session. Long-term recovery does not rely on runToken or advance an old run. Requires billing:write and funnels:run.

  Returns NativeReceiptResponse