Products
A product is the catalog entry for one thing you charge for. A per-user seat, a platform fee, a gigabyte of transfer, a one-off setup charge.
Products carry no money of their own. They describe what you are selling and, most importantly, where the billed quantity comes from. You might state that quantity yourself, let your customer choose it, or have a meter measure it. Prices then decide what that quantity costs, and a plan bundles priced products into something a customer can subscribe to.
That separation is deliberate. One product can appear in several plans at different prices, in several currencies, and on a one-off invoice, without ever being duplicated. When you rename it, every plan that uses it follows.
The three product types
The first thing you choose when creating a product is its type. This single choice decides where the billed quantity comes from, so the rest of the product depends on it. All three are worth understanding before you pick one.
Flat fee
A fixed recurring charge whose quantity is always one. Use it for a base subscription fee, a platform fee, or a one-time setup charge.
Nothing is counted and nothing varies. Whatever the customer does during the period, the line is the same.
Per seat / license
This is the workhorse of most subscription businesses, and it is the type people most often overlook.
The quantity here is a level rather than a total. Twelve seats, three licences, forty vehicles, five connected devices. You set that level, or you let the customer choose it at checkout, and it carries from one period to the next until somebody changes it. When somebody does change it mid-period, Kontier works out the difference and prorates it across the remainder of the period for you.
Everything that makes per-seat software work rests on this type. Plans can include a number of seats, buyers can add more from the portal, and mid-cycle upgrades and downgrades settle correctly without you calculating anything.
Usage-based
Consumption that a meter accumulates inside one billing period. API calls, gigabytes transferred, minutes, resolved DNS queries.
Every period starts again from zero, so nothing carries forward unless you explicitly configure rollover.
A usage-based product does nothing until you bind a meter to it. The dashboard marks this with a Needs meter binding badge, and billing produces no line at all until that binding exists.
The type is permanent
You choose the type once, when you create the product. There is no way to change it afterwards. To switch, archive the product and create a new one. The unit label and the pricing model both stay editable.
Create it in the dashboard
We will create a Premium Support Seat, a named on-call engineer billed per seat per month. That makes it a Per seat / license product.
-
Open the Products page
There are three ways to get there, and they all end up in the same place.
The most direct is the sidebar. Under Billing, click Products.
If you prefer the keyboard, press ⌘K to open the command palette and start typing
products. The palette also lists a shortcut beside each destination, so once you know it you can press G then P from anywhere in the dashboard and skip the palette entirely.⌘K opens the command palette, which lists the direct shortcut for each page -
Start a new product
Click New Product, at the right-hand end of the toolbar above the list.
-
Choose the type and name the unit
Pick Per seat / license. Each option shows an example of the invoice line it produces, which is usually enough to confirm you have chosen correctly.
Then fill in Unit label with
seat. This is the noun your customers read on their invoices and in the portal, so an invoice says "12 seats" rather than "12 units". You can change it later.Step 1 of 2. The type decides where the billed quantity comes from. -
Configure the product
Click Continue and name the product
Premium Support Seat.Two fields on this step matter more than they look. Public Description is shown to your customers on invoices and in the portal, while the plain Description stays internal, so fill in the public one if you only fill in one. Customers pick a quantity controls whether checkout shows a quantity stepper, which you want for seats but not for anything a buyer should not be choosing.
Pricing Model decides how tiered prices are applied once you attach them. Volume applies a single tier's rate to every unit, while Staircase prices each tier separately. If you have no tiers yet, leave it on Volume, because you can change it later.
Step 2 of 2. The Per seat badge carries over from the previous step. -
Create it
Click Create Product. You land on the product's detail page.
The product now exists, but it has no price, so it cannot be sold yet. Prices live on the Prices tab of the detail page, which is where the next step picks up.
The Prices tab, where the next step adds the price
Create it with the API
The same product in a single call. The dashboard's three types map onto two API fields, which the table in the next section spells out.
Dashboard and API names
The dashboard names things for the person configuring a catalog, and the API names them for the person integrating one. They are the same fields underneath.
| In the dashboard | In the API |
|---|---|
| Flat fee | quantity_source: "DECLARED", quantity_adjustable: false |
| Per seat / license | quantity_source: "DECLARED", quantity_adjustable: true |
| Usage-based | quantity_source: "METERED", plus a meter binding |
| Unit label | unit_label |
| Customers pick a quantity | quantity_adjustable |
| Public Description | public_description |
| Tax Category | tax_category |
| Pricing Model: Volume, Staircase, Package | pricing_model: "VOLUME" | "STAIRCASE" | "PACKAGE" |
Where products go next
A product on its own bills nothing. In order:
- Add a price, for example
CHF 159.00per seat per month with volume breaks at 5, 15 and 50 seats. Until you do, the product cannot be sold. - Put it in a plan. Plans bundle priced products into a subscribable package, and one product can sit in as many plans as you like.
- Subscribe a customer. The subscription carries the quantity for per-seat products and prorates any change to it.
- Bind a meter, for usage-based products only. Nothing bills until you do.
Once a subscription bills, each product becomes a line on the invoice, showing the quantity, the unit price, the tax rate and the resulting amount.
Next step
Continue to Prices and attach a price to the product you just created.
Reference
| Topic | When you need it |
|---|---|
| Pricing models | How Volume, Staircase and Package apply tiers, and formula expressions |
| Key sets | One product carrying hundreds of price variants, such as TLDs or instance types |
| Product costs | Cost-plus pricing and margin reporting |
| Meter bindings | Connecting a usage-based product to an aggregator |
| Products API | Every field, endpoint and error code |
Not everything is public yet
A few product operations are available in the dashboard but not yet in the public API, while we finish tidying them up. If you need one of them from your own system, email engineering@kontier.eu and we will talk you through the options.