Skip to main content
This guide sets up a real deal shape: an API product billed on metered usage, with tiered rates, a monthly free-call allowance, and quarterly invoicing in two currencies. It chains together several module-level walkthroughs and how-to guides rather than repeating their steps here; each phase links to the one it depends on.

​
What this guide sets up

  • A point in time product, “API calls,” measured by quantity, priced with tiered rates that reset monthly even though invoicing happens quarterly
  • Two pricing presets on that product, one in USD and one in EUR
  • A quantity discount giving the customer 10,000 free calls every month
  • A contract that puts all of this together and bills a full quarter in one invoice

Products: concepts

Product type, pricing model, and pricing preset, the concepts this guide configures.

Discounts: concepts

How a quantity discount’s pool and cadence work.

​
Phase 1: Create the product

Follow products: walkthrough to create a new product:
  • Name: API calls
  • Type: Point in time
  • Subtype: Quantity
  • Unit: “API call” / “API calls”

​
Phase 2: Configure the USD pricing preset

Continuing the same walkthrough’s pricing step:
  • Pricing model: Tiered
    • Tier 1: 0 to 100,000 calls at $0.01
    • Tier 2: 100,000 to 1,000,000 calls at $0.005
    • Tier 3: 1,000,000+ calls at $0.001
  • Currency: USD
  • Usage is metered: on, pointing at an aggregate that counts API call events
  • Quantity strategy: Recurring
  • Tier reset period: Monthly
Setting the tier reset period to monthly here, independent of whatever billing cadence the contract ends up using, is what makes the rest of this guide interesting: billing will happen quarterly, but the tiers reset every month regardless. See product type: point in time for why that’s a legal combination (a monthly reset tiles evenly into quarterly billing) and what it would mean if it didn’t.

​
Phase 3: Add a EUR pricing preset

Follow manage products: add another pricing preset, repeating the same tiered configuration but with Currency set to EUR instead. Because this is the first EUR preset on the product, it becomes the EUR default automatically, the same way the USD preset became the USD default; nothing further to configure for that.

​
Phase 4: Set the tax category

Follow add a product: phase 1 to assign a tax category such as “SaaS - digital services” to the product, if not already set when it was created.

​
Phase 5: Create the contract and add the product

Follow contract: walkthrough to create a contract for the customer, in USD, with quarterly billing. Add the “API calls” product as a line item; since the contract is USD, the USD preset applies automatically through use catalog pricing.

​
Phase 6: Add the quantity discount

Follow how to add a discount to a line item:
  • Strategy: Quantity
  • Value: 10,000 units
  • Cadence: Monthly
The discount’s monthly cadence is shorter than the contract’s quarterly billing cadence, so each month gets its own 10,000-unit pool rather than one pool shared across the quarter. See discounts: quantity discount for how that case differs from a cadence that matches or exceeds the billing period.

​
Phase 7: Preview the quarter

Turn on invoice preview, following contract: walkthrough, step 4. With usage of 150,000 calls in January, 80,000 in February, and 300,000 in March, the quarterly invoice works out to:
Each month’s tiers reset independently, since the tier reset period is monthly, and each month’s discount pool is separate, since the discount’s cadence is also monthly. The quarterly billing cadence only determines when the invoice is actually issued, one invoice summing all three months, not how the usage within it was calculated.

​
Phase 8: Publish

Follow contract: walkthrough, step 5 to publish the contract and start generating invoices on the quarterly cadence.