One-time purchases

One-time purchases are optional single purchases on a subscription plan. For example, AI credit packs, storage top-ups, or feature unlocks. You configure them on the plan under One-time charges. Customers buy them after they subscribe, or you assign them from the admin.

What you need

Link to this section

• One-time purchases are configured per plan. See Create billing plans — Add one-time charges.
• Customers need a saved payment method to buy from the portal, unless you assign a complimentary purchase from the admin.
• Purchases attach to the customer’s current billing agreement. They do not survive a plan change or cancellation.

What customers can buy

Link to this section

Each one-time purchase on a plan can be:

Setting	Options
Usage	Unmetered (access only) or Metered (track consumption against purchased units)
Pricing	Flat (fixed price per purchase) or Package (price per set number of units)
Expiry	Never expires or Expires with the billing cycle

On the plan details page, purchased items show units granted, amount paid, expiry, and current usage for metered purchases.

Buy from the self-serve portal

Link to this section

Authorized customers can buy one-time purchases from the portal Plan page.

1. Enable the self-serve portal and plan management. See Self-serve portal for users or Self-serve portal for organizations.

2. For B2B organization billing, ensure the organization member has a role with the org:write:billing system permission (for B2C users, billing write access is granted automatically).

3. The customer opens the portal and goes to Plan.

4. In One-time purchases, they select Purchase or Buy more.

5. For package-priced purchases, they choose how many packages to buy, then confirm payment.

   

If no payment method is on file, the customer is prompted to add one before checkout completes.

Assign from the Kinde admin

Link to this section

You can grant a one-time purchase without the customer going through the portal:

1. Open the user or organization and select Billing.

2. In the One-time purchases section, select Assign or Assign more.

   

3. For package-priced purchases, enter the number of packages.

4. Choose:

   • Charge default payment method — invoices and charges the customer’s saved card
   • Assign without charge — grants the purchase at no cost

You need permission to create billing agreements.

Metered one-time purchases

Link to this section

When a one-time purchase is metered, purchased or assigned units set the allowance. You can record consumption via the Management API after the first purchase or admin assignment (paid or complimentary) completes.

• Never expires — usage is tracked as a lifetime total for that agreement and feature.
• Expires with the billing cycle — usage resets each billing cycle, like recurring metered features.

See Add metered usage for a customer via API.

Plan changes and cancellations

Link to this section

One-time purchases belong to the current billing agreement.

Event	What happens
Customer changes plan	Active one-time purchases on the old agreement are forfeited. Kinde lists them in the confirmation dialog. No refund is issued.
Customer cancels	The same forfeiture rules apply. The cancel dialog warns when active purchases exist.
Customer buys again on a new plan	Treated as a new purchase. Prior payment is not credited.

See Subscription upgrade and downgrade methods and Cancel a subscription.

Management API

Link to this section

API reference for these endpoints is generated from the OpenAPI spec:

Endpoint	Purpose
GET /api/v1/billing/one_time_purchases	List current paid, non-expired purchases for a customer
GET /api/v1/billing/meter_usage	Page usage records and read the grant snapshot
POST /api/v1/billing/meter_usage	Record usage, including metered one-time purchases after the first purchase or assignment

Enable the read:billing_one_time_purchases, read:meter_usage, and create:meter_usage scopes on your M2M application as needed.

Deleting plans with one-time purchases

Link to this section

You cannot delete a plan while customer one-time purchase records still reference a published plan version on that plan. Remove or migrate customers first.