Create new contracts and billing terms
This guide walks through creating the entities that define a billing arrangement in Tabs: the contract that establishes the relationship and the billing terms that generate invoices.
Step 1: Create the contract
A Contract defines the billing arrangement with a customer. It serves as the container for the Billing Terms—grouped into Billing Term Groups—that generate invoices. This guide assumes that the customer already exists. If not, create one first using POST /v3/customers.
Create the contract:
Save the returned id as {contractId}.
When a customer upgrades, downgrades, or changes their terms mid-contract, create a new contract to represent the amendment. This preserves a clean audit trail.
Step 2: Add billing terms to the contract
A billing term defines what you’re charging, how much it costs, and on what schedule. Each billing term generates the line items that appear on invoices. A contract can have multiple billing terms, organized into billing term groups. Performance obligations are created automatically when the billing term is generated to help create a revenue schedule downstream.
Before creating billing terms, look up the {itemId} you need using GET /v3/items.
Flat-rate billing term
A one-off or recurring fixed charge:
Usage-based billing term
A per-unit billing term linked to an event type. Create the event type first using POST /v3/events/types, then reference its id in the eventTypeId field:
Seat-based billing term
A per-unit billing term where seat count changes over time are tracked and billed via seat amendments. Set seatConfig to mark the billing term as seat-based: