Products and plans
Products and plans together define what the customer is buying and how they are charged for it. A product is the thing being sold; a plan is the pricing template applied to that product.
Product
The product that a merchant sells. A merchant can sell many products, and a product can be attached to one or more plans. A product can be a physical good or a service.
The same product can have different pricing depending on the plan it is attached to — for example, a "Premium" plan and a "Premium Annual" plan can both point at the same product with different recurringInterval and price values.
For CRUD operations, see Product CRUD.
Plan
A plan is the template of the key terms describing a subscription or a one-time purchase. A plan defines:
- The product it applies to (
productId). - The price and currency (
pricing). - Optional setup fees.
- Optional trial period and trial price (
trial). - Optional recurring billing cadence (
recurringInterval). - Optional expiry or invoice limit.
Three categories of plans
Whether recurringInterval and trial are set decides which category a plan falls into:
| Category | Has recurringInterval? | Has trial? | Used with |
|---|---|---|---|
| Trial-only | No | Yes (the only billable period) | POST /subscriptions with isTrialOnly: true |
| One-time order | No | No | POST /subscriptions/one-time-orders |
| Subscription | Yes | Optional | POST /subscriptions |
A "one-time order with trial" is a special case of Subscription: a plan with recurringInterval.limit: 1 and a trial block. Created via POST /subscriptions, it charges once (after the trial) and then ends. See Subscriptions for the full list of categories.
For the endpoint comparison and what happens when you use the wrong combination, see One-time order.
For the recurring cadence field, see Recurring interval. For trial behavior, see Trial. For CRUD operations on a plan, see Plan CRUD.
Pricing
The plan's pricing block defines the formula and the price. PaymentsAI supports several pricing models: fixed fee, flat rate, tiered, volume, and stair-step. For the catalogue, see Pricing.