Skip to main content

​
Contracts

Contracts are the active subscriptions between your customers and plans. They determine what a customer is billed for.

​
What is a Contract?

A contract connects:
  • A customer who pays
  • A plan that defines pricing
  • Terms like start date and billing cycle
{
  "customerId": "cust_123",
  "planId": "plan_pro",
  "startDate": "2026-02-01",
  "billingCycleAnchor": "2026-02-01"
}

​
Contract Lifecycle

StateDescription
ACTIVECustomer is being billed according to the plan
CANCELLEDContract has been terminated, no future billing

​
How Contracts Work

  1. Contract starts — First invoice is generated
  2. Base fee applied — Plan’s recurring fee added to invoice
  3. Usage accumulates — Events matching plan’s meters are tracked
  4. Billing cycle ends — Usage is finalized and invoiced
  5. Cycle repeats — Next invoice generated, usage resets

​
Creating Contracts

​
Required Fields

FieldDescription
customerIdWhich customer this contract is for
planIdWhich plan to subscribe them to
startDateWhen billing begins

​
Optional Fields

FieldDescription
endDateWhen contract automatically ends (for fixed-term)
billingCycleAnchorDay of month for billing (e.g., always bill on the 1st)
netTermsDays until payment due (default: 0)

​
Billing Cycle Anchor

The billing cycle anchor determines when invoices are generated. Example: Monthly plan with anchor on the 15th 
Feb 15 → Invoice for Feb 15 - Mar 14
Mar 15 → Invoice for Mar 15 - Apr 14
Apr 15 → Invoice for Apr 15 - May 14
If not specified, the billing cycle anchor defaults to the contract start date.

​
Plan Changes

Customers can change plans mid-cycle:

​
Upgrade Behavior

  1. Current invoice is finalized with prorated usage
  2. New plan takes effect immediately
  3. Prorated base fee for remainder of cycle

​
Downgrade Behavior

  1. New plan takes effect at next billing cycle
  2. Current cycle continues on old plan
  3. No proration (they paid for the current cycle)

​
Cancellation

When a contract is cancelled:
  1. Immediate: Contract ends now, final invoice generated with usage to date
  2. End of period: Contract continues until billing cycle ends
{
  "contractId": "contract_123",
  "cancellationType": "END_OF_PERIOD"
}
Cancelled contracts cannot be reactivated. Create a new contract if the customer returns.

​
Multiple Contracts

A customer can have multiple active contracts:
  • Different products (e.g., API access + Data platform)
  • Separate billing for different teams or projects
  • Gradual migration between plans
Each contract generates its own invoices.

​
Contract vs Invoice

ConceptDescription
ContractOngoing relationship defining what to bill
InvoicePoint-in-time bill for a specific period
One contract generates many invoices over its lifetime.

​
Next Steps

How Usage-Based Billing Works

See how contracts fit into the full billing flow

Create Your First Contract

Step-by-step guide

Contracts API

API reference

Enterprise Billing

Custom rates and prepaid commitments

Plan Changes

Upgrade or downgrade

Cancellation

End a contract