Skip to main content
Your catalog has four layers. Most products only use the first three; charges matter when one plan bills several things.

​
The quick way: a product with one price

For a simple plan, create the product with its price in one call. Bouclay creates a plan alongside it:
The response lists the new priceIds and the plan.

​
Several plans on one product

Create the product, then each plan, then each plan’s prices:
A plan can offer several intervals and currencies: add one price for each. When you subscribe a customer you can name the plan and Bouclay picks the price that matches.

​
Prices never change once used

A price that a subscription or invoice has used is frozen: its amount, currency and interval can’t be edited. This protects every invoice already issued. To change what you charge, create a new price and archive the old one. Existing subscribers stay on the old price until you move them. See Changing subscriptions.

​
Billing intervals

billingInterval is day, week, month or year, and billingFrequency multiplies it: month with 3 bills every three months.

​
Pricing models

graduated, volume and package are early access.
Tiers are a list of upTo (the last one null) and unitAmount, with an optional flatAmount for the tier. Included units are a first tier at 0:

​
Seats and quantity limits

A licensed price charges for a quantity you set, such as seats. minQuantity and maxQuantity set a range (“Team: 5 seats or more”); anything outside it is refused. Name the unit on the charge with unitLabel and unitLabelPlural (PATCH /charges/{id}), and invoices read “Team · 3 learners” instead of a bare number.

​
Free trials

Add trialLength and trialUnit (day, week or month) to a recurring price.
  • trialRequiresPaymentInfo: true starts the trial only once the customer saves a card. Without it, the trial starts at once with no card.
  • trialOncePerCustomer: true gives each customer one trial per plan.
What happens when a trial ends without a card is set per subscription. See Subscriptions.

​
Setup and joining fees

setupFee on a recurring price is billed once, on a new subscription’s first paid invoice: at once, or when a trial ends. Name the line with setupFeeName (such as “Joining fee”). It is never billed on a renewal, a plan change or a resume. setupFeeAgainAfterMonths lets a returning customer back without paying it again, unless that many months have passed since their last subscription to the product ended.

​
Plans with several charges

A plan can bill several things together, such as a platform fee plus two kinds of usage. Each is a charge with its own prices, and the invoice shows one line per charge. See Sell several kinds of usage in one plan.

​
Taxes on products

Each product has a tax category: standard, zero_rated or exempt. A charge can override it. See Invoices.

​
Archiving

Archive products, plans, prices and charges you no longer sell. Archived items can’t start new subscriptions; existing subscriptions keep billing. To move everyone off a plan on a date, see Retire a plan.