Billing - UnitPay

The Quickstart ran the credit path with no card. This page covers the dollar path: what a plan is, how a customer subscribes and pays, and where the invoice lands. It’s written for self-serve (PLG) products — subscriptions a customer starts themselves and pays by card.

The catalog

You sell plans, which live under a product. A plan carries:

Charges — the price (a $20/month recurring charge, a usage charge, a one-off).
Entitlements — the features the plan unlocks, read by check.
Grant rules — optional credit grants that refill each cycle.

Create them with the catalog API (POST /v1/products, POST /v1/plans) or let Asterix build the whole catalog from your pricing page.

Subscribing and paying

You always subscribe the same way — POST /v1/subscriptions — and the response tells you how money moved. It’s a single outcome object discriminated by kind:

`kind`	When	What you do
`created_no_charge`	Free/$0 plan, or trial with no card	Nothing — the subscription is active.
`charged_inline`	Paid plan and a card already on file	Nothing — the card was charged and the first invoice is paid.
`requires_form`	Paid plan, no card yet	Collect a card in the browser, then it settles.
`deferred`	Change scheduled for later (e.g. downgrade)	Applies at the next cycle.

curl https://api.useunitpay.com/v1/subscriptions \
  -H "x-api-key: $UNITPAY_SECRET_KEY" \
  -H "content-type: application/json" \
  -d '{ "customerId": "cus_123", "planId": "pln_pro" }'

Collecting the first card

The first card-on-file is collected in the browser with Stripe Elements — a card number can’t be sent to the API directly. When POST /v1/subscriptions returns requires_form, it includes a client secret; mount the React SDK’s payment form with it, and the subscription settles once the card is confirmed (a webhook provisions the subscription, invoice, and any credits).

import { useCreateSubscription } from '@unitpay/react';

const { createSubscription } = useCreateSubscription({
  onChargedInline: () => alert('Subscribed and paid ✓'),
  onRequiresForm: (r) => setFormClient(r.client), // render <PaymentForm> with this
  onCreated: () => alert('Subscription active.'),
});

createSubscription({ planId: 'pln_pro' });

Once a card is saved, later charges — renewals, plan changes, and credit top-ups — are charged_inline automatically, no form needed. See the React SDK for the full checkout UI.

In sandbox, use Stripe’s test card 4242 4242 4242 4242 with any future expiry and any CVC.

Invoices

When a paid subscription settles, UnitPay creates an invoice and auto-charges the card (collectionMethod: "charge_automatically"). Read a customer’s invoices, filtered by status:

curl "https://api.useunitpay.com/v1/invoices?customerId=cus_123&status=paid" \
  -H "x-api-key: $UNITPAY_SECRET_KEY"

Fetch one for its line items and payments:

curl https://api.useunitpay.com/v1/invoices/inv_123 \
  -H "x-api-key: $UNITPAY_SECRET_KEY"

Renewals bill automatically each cycle. If a renewal charge fails, the subscription goes past_due and the open invoice can be paid with POST /v1/invoices/:id/pay.

Next steps

Credits & top-ups

Sell credit packages and refill balances — same card-on-file flow.

React SDK

Pricing table, checkout, and the payment form.

How it works

The two paths and the two verbs.

Quickstart

The credit path, end to end.

​The catalog

​Subscribing and paying

​Collecting the first card

​Invoices

​Next steps

Credits & top-ups

React SDK

How it works

Quickstart

The catalog

Subscribing and paying

Collecting the first card

Invoices

Next steps