One-off purchases use the billing provider

A report can be a one-time item in the product catalogue. Its checkout uses payment mode through the existing billing provider.

One-off purchases use the billing provider

One-time items and credit packs use the same billing provider and hosted checkout as subscriptions. Selecting a separate payment vendor independently of subscription billing is not an available configuration.

Example — Sell a report alongside a subscription

A report can be a one-time item in the product catalogue. Its checkout uses payment mode through the existing billing provider.

For engineers

One-time products use the same registered catalogue, scoped account and openCheckout action as plans. Product type selects the checkout mode: PLAN, ADDON and METERED use subscription mode; ONE_TIME, ITEM and CREDIT_PACK use payment mode. An absent price interval describes a non-recurring price.

This complete catalogue entry sells a pack of report credits. Add it to the shared module’s productDefinitions alongside the rest of the catalogue. The identifiers and amounts are an illustrative application offer.

import { ProductType, ResourcePrimaryScope, type ProductDefinition } from '@wildo-ai/saas-models';
import { PricingModel } from '@wildo-ai/external-connectors-models';
import { AvailableCurrency } from '@wildo-ai/zod-decorators';

export const reportCredits: ProductDefinition = {
  key: 'report-credits',
  type: ProductType.CREDIT_PACK,
  targetScopes: [ResourcePrimaryScope.ORGANIZATIONS],
  purchaseConfig: {
    creditsPerUnit: 10,
    creditPoolKey: 'reports',
    maxQuantityPerPurchase: 5,
  },
  prices: [{
    model: PricingModel.FLAT,
    unitPrice: { amount: 1000n, decimals: 2, currency: AvailableCurrency.USD },
    intervalCount: 1,
    isDefault: true,
  }],
};

Resolve the synchronized product by report-credits and its own active price from useBilling(), then call openCheckout(product.key, price._id, { quantity: 2 }). Use the same loading, availability and error handling shown in hosted checkout, but call checkout directly for this pack even if a plan subscription already exists. The example’s two units cost USD 20 before any tax or promotion and correspond to twenty report credits.

Let confirmed payment produce the result

The signed checkout completion path resolves the trusted account and product, validates settlement and deduplicates delivery. For CREDIT_PACK with a creditPoolKey, it computes creditsPerUnit × quantity and tops up that scoped pool. The billing credit view can then show the recorded balance; a checkout redirect alone must not increment it.

Product	Checkout	Application result
Credit pack	One payment, no recurring interval	Confirmed completion tops up the configured credit pool
One-time item	One payment, no recurring interval	The application owns fulfillment of the purchased item
Plan	Subscription with recurring price	Subscription state and configured grants follow provider events

Credit consumption is separate from purchasing: connect the operation that generates a report to the credit pool mechanism. Calling an item “a report” does not install report generation or delivery.

Keep provider selection on the billing path

Enable EngineCapability.BILLING and configure its provider. There is no independently selectable payment-provider contract; the retired BILLING_PAYMENTS name is not an alternative vendor slot. One-time checkout uses the billing provider already connected to this account.

One-off purchases use the billing provider