What are products and prices?
In ODUS, products and prices are the building blocks for billing. Before you can create a subscription or charge a customer, you need at least one product with at least one price attached to it.
Products
A product represents a sellable item or service in your catalog — for example, a SaaS plan, a physical product, or a content subscription. A product does not contain any billing information on its own. It has a name, an optional description, and an optional statement descriptor.
The statement descriptor is the text that appears on a customer's bank statement when they are charged. It is limited to 22 characters.
A product can also have a statement descriptor suffix: a short text that some gateways add after your account's own descriptor instead of replacing it. See Statement descriptors.
Prices
A price defines the billing terms for a product. Every price belongs to exactly one product and specifies:
- The amount to charge, in the smallest currency unit (for example, cents for USD).
- The currency to charge in.
- The type of charge: either
one_timeorrecurring.
One-time prices
A one-time price charges the customer a fixed amount exactly once. This is suitable for setup fees, lifetime access purchases, or any charge that is not repeated.
Recurring prices
A recurring price charges the customer on a repeating schedule. The price's amount is what each billing cycle charges, in the smallest currency unit, and its recurringSchedule sets how often:
| Field | Description |
|---|---|
intervalUnit | The unit of time for the billing interval: minute, hour, day, week, month, or year. |
intervalCount | The number of units between each charge. For example, 1 with month means monthly. |
trial | Optional. A first cycle with its own intervalUnit, intervalCount and amount. |
For example, a monthly plan at $29.99 has amount: 2999 and recurringSchedule: { "intervalUnit": "month", "intervalCount": 1 }. See Attaching a recurring price for a full request.
Multiple prices per product
A product can have more than one price. This is how you offer different billing options for the same service. For example, a "Pro Plan" product might have a monthly price and an annual price. When creating a subscription, you specify which price to use, not just which product.
This also makes it possible to add new pricing options later without touching existing subscriptions. Existing subscriptions keep their original price until you explicitly change them.
Products, prices, and subscriptions
When a customer subscribes to something, you create a subscription by referencing a price. ODUS looks up the product and recurring schedule from that price automatically. The subscription then renews according to that schedule.
This relationship can be summarised as:
- A product describes what is being sold.
- A price describes how it is billed.
- A subscription is a specific customer's active agreement to be billed according to a price.
Statement descriptors
Card statements show at most 22 characters, and gateways build that text in one of two ways. That is why a product has two descriptor fields:
| Field | What the gateway does with it | Used by |
|---|---|---|
statementDescriptor | Replaces your account's descriptor with this text | Adyen, Checkout.com, and Stripe by default |
statementDescriptorSuffix | Adds this text after your account's descriptor | PayPal, and Stripe when the gateway profile's suffix option is on |
Write the suffix to be read after your account's descriptor, and keep it short. The gateway shows your account's descriptor, a separator, then the suffix, and cuts the line at 22 characters. For example, with the account descriptor ACME, the suffix PRO PLAN reads ACME* PRO PLAN on a Stripe statement.
- PayPal sends the suffix when the payment has one, and the full descriptor otherwise.
- Stripe sends the full descriptor unless you turn on Send the statement descriptor suffix instead of the full descriptor on the gateway profile; see Stripe.
A payment takes both values from the product of its first cart item. You can override either one when you create the payment, and each falls back to the product separately. Subscription payments take them from the subscribed product.