Skip to main content
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:
kindWhenWhat you do
created_no_chargeFree/$0 plan, or trial with no cardNothing — the subscription is active.
charged_inlinePaid plan and a card already on fileNothing — the card was charged and the first invoice is paid.
requires_formPaid plan, no card yetCollect a card in the browser, then it settles.
deferredChange 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.