Configure custom billing solutions
Tabs generates invoices based on rules you define in a billing term.
You create a billing term on an existing contract with POST /v3/contracts/{contractId}/billing-terms—the fields you set control when Tabs invoices, how much it charges, and how often.
This guide covers the most common configurations, each with the specific API call.
For billing setups beyond these options, Tabs’ Engineering team can build a custom integration. Contact your Implementation Manager or Customer Success Manager with your use case. Tabs builds and maintains the integration, so you don’t need to write or deploy any code.
Before you begin
You need:
- An API key, passed as
Authorization: YOUR_API_KEYon every request. Contact your Tabs Implementation Manager if you don’t have one. - An existing contract
id, referenced below as{contractId}. To create one, see Invoice a customer. - Optionally, an item
id({itemId}) to map the line item to an account in your ERP.
Bill in advance
To charge customers at the start of each billing period—common for subscriptions and annual licenses—set invoiceDateStrategy to FIRST_OF_PERIOD. Tabs generates the invoice on the first day of each period and sets the due date to netPaymentTerms days later.
netPaymentTerms sets the number of days between the invoice issue date and its due date. Adjust it to match the payment terms in the contract.
The following example bills a flat $120,000 annually, in advance, with 30-day payment terms:
Tabs returns the created billing term:
Save the id—you’ll reference it as {billingTermId} to update or cancel the billing term later.
Billing terms activate immediately. To review the first invoice before it’s sent, check it while it’s in DRAFT status.
Collect payment before service begins
To ensure payment is received before service starts, use ADVANCED_DUE_START. Tabs works backward from the service start date: if a period starts January 1 with 30-day net terms, Tabs issues the invoice on December 2 and sets the due date to January 1.
Bill at end of period
To generate invoices on the last day of each billing period, set invoiceDateStrategy to LAST_OF_PERIOD. The invoice issue date is the final day of the period (for example, January 31 for a January billing period); the due date is netPaymentTerms days after that.
This differs from ARREARS by one day: ARREARS issues the invoice on the first day of the next period (February 1), which can matter for payment term calculations and customer-facing invoice dates.
Bill after service delivery
To invoice after the service period ends, set invoiceDateStrategy to ARREARS. Tabs generates the invoice on the first day of the following period—for a January billing period, the invoice is issued February 1. Use this for usage-based billing where you collect metered data throughout the period and submit final figures at close.
After the period ends, submit usage data against the billing term before Tabs invoices.
Include multiple charges on one invoice
Each billing term produces one line item. To consolidate multiple charges—such as a platform fee and a one-time onboarding fee—onto the same invoice, create multiple billing terms on the same contract and assign them to the same Billing Term Group.
Create the first billing term without a billingTermGroupId. The response includes a billingTermGroupId; pass that value on each additional billing term you want on the same invoice:
Both line items appear on the same invoice as long as their billing periods align.
Bill at a custom frequency
Use interval and intervalFrequency together to control billing cadence. Set interval to the unit (DAY, HOUR, WEEK, SEMI_MONTH, MONTH, or YEAR) and intervalFrequency to the number of units between invoices. The following example bills quarterly ($15,000 every three months):
For a one-time charge, set isRecurring to false and interval to NONE.
Use tiered pricing
To charge different rates based on usage volume, set pricingType to TIERED and provide multiple pricing entries with ascending tierMinimum values. Tabs applies the rate for the tier the usage quantity falls into.
The following example charges 8/unit for 101–500, and $6/unit above 500: