> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.tabs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.tabs.com/_mcp/server.

# 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_KEY` on 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](/invoice-customer-quickstart).
* 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:

```bash
curl -X POST https://integrators.prod.api.tabsplatform.com/v3/contracts/{contractId}/billing-terms \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Annual platform license",
    "billingStartDate": "2025-01-01",
    "isRecurring": true,
    "interval": "YEAR",
    "intervalFrequency": 1,
    "invoiceDateStrategy": "FIRST_OF_PERIOD",
    "netPaymentTerms": 30,
    "quantity": 0,
    "billingType": "FLAT",
    "pricingType": "SIMPLE",
    "itemId": "{itemId}",
    "pricing": [
      {
        "tier": 1,
        "amount": 120000.00,
        "amountType": "TOTAL_INVOICE",
        "tierMinimum": 0
      }
    ]
  }'
```

Tabs returns the created billing term:

```json
{
  "payload": {
    "id": "9f8b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d",
    "contractId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Annual platform license",
    "billingStartDate": "2025-01-01",
    "billingEndDate": "2025-12-31",
    "isRecurring": true,
    "interval": "YEAR",
    "intervalFrequency": 1,
    "netPaymentTerms": 30,
    "billingTermGroupId": "f0e1d2c3-4567-4abc-8def-222222222222",
    "createdAt": "2025-01-01T12:00:00Z"
  },
  "success": true,
  "message": "Billing term created successfully",
  "error": null
}
```

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.

```bash
curl -X POST https://integrators.prod.api.tabsplatform.com/v3/contracts/{contractId}/billing-terms \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly subscription",
    "billingStartDate": "2025-01-01",
    "isRecurring": true,
    "interval": "MONTH",
    "intervalFrequency": 1,
    "invoiceDateStrategy": "ADVANCED_DUE_START",
    "netPaymentTerms": 30,
    "quantity": 0,
    "billingType": "FLAT",
    "pricingType": "SIMPLE",
    "itemId": "{itemId}",
    "pricing": [
      {
        "tier": 1,
        "amount": 5000.00,
        "amountType": "TOTAL_INVOICE",
        "tierMinimum": 0
      }
    ]
  }'
```

## 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.

```bash
curl -X POST https://integrators.prod.api.tabsplatform.com/v3/contracts/{contractId}/billing-terms \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly retainer",
    "billingStartDate": "2025-01-01",
    "isRecurring": true,
    "interval": "MONTH",
    "intervalFrequency": 1,
    "invoiceDateStrategy": "LAST_OF_PERIOD",
    "netPaymentTerms": 15,
    "quantity": 0,
    "billingType": "FLAT",
    "pricingType": "SIMPLE",
    "itemId": "{itemId}",
    "pricing": [
      {
        "tier": 1,
        "amount": 3000.00,
        "amountType": "TOTAL_INVOICE",
        "tierMinimum": 0
      }
    ]
  }'
```

## 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.

```bash
curl -X POST https://integrators.prod.api.tabsplatform.com/v3/contracts/{contractId}/billing-terms \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly API usage",
    "billingStartDate": "2025-01-01",
    "isRecurring": true,
    "interval": "MONTH",
    "intervalFrequency": 1,
    "invoiceDateStrategy": "ARREARS",
    "netPaymentTerms": 15,
    "quantity": 0,
    "billingType": "UNIT",
    "pricingType": "SIMPLE",
    "itemId": "{itemId}",
    "pricing": [
      {
        "tier": 1,
        "amount": 0.50,
        "amountType": "PER_ITEM",
        "tierMinimum": 0
      }
    ]
  }'
```

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:

```bash
curl -X POST https://integrators.prod.api.tabsplatform.com/v3/contracts/{contractId}/billing-terms \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding fee",
    "billingStartDate": "2025-01-01",
    "isRecurring": false,
    "interval": "NONE",
    "intervalFrequency": 1,
    "invoiceDateStrategy": "FIRST_OF_PERIOD",
    "netPaymentTerms": 30,
    "quantity": 0,
    "billingType": "FLAT",
    "pricingType": "SIMPLE",
    "pricing": [
      {
        "tier": 1,
        "amount": 5000.00,
        "amountType": "TOTAL_INVOICE",
        "tierMinimum": 0
      }
    ]
  }'
```

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):

```bash
curl -X POST https://integrators.prod.api.tabsplatform.com/v3/contracts/{contractId}/billing-terms \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quarterly subscription",
    "billingStartDate": "2025-01-01",
    "isRecurring": true,
    "interval": "MONTH",
    "intervalFrequency": 3,
    "invoiceDateStrategy": "FIRST_OF_PERIOD",
    "netPaymentTerms": 30,
    "quantity": 0,
    "billingType": "FLAT",
    "pricingType": "SIMPLE",
    "itemId": "{itemId}",
    "pricing": [
      {
        "tier": 1,
        "amount": 15000.00,
        "amountType": "TOTAL_INVOICE",
        "tierMinimum": 0
      }
    ]
  }'
```

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 $10/unit for the first 100 units, $8/unit for 101–500, and \$6/unit above 500:

```bash
curl -X POST https://integrators.prod.api.tabsplatform.com/v3/contracts/{contractId}/billing-terms \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Volume API calls",
    "billingStartDate": "2025-01-01",
    "isRecurring": true,
    "interval": "MONTH",
    "intervalFrequency": 1,
    "invoiceDateStrategy": "ARREARS",
    "netPaymentTerms": 30,
    "quantity": 0,
    "billingType": "UNIT",
    "pricingType": "TIERED",
    "itemId": "{itemId}",
    "pricing": [
      {
        "tier": 0,
        "amount": 10.00,
        "amountType": "PER_ITEM",
        "tierMinimum": 0
      },
      {
        "tier": 1,
        "amount": 8.00,
        "amountType": "PER_ITEM",
        "tierMinimum": 101
      },
      {
        "tier": 2,
        "amount": 6.00,
        "amountType": "PER_ITEM",
        "tierMinimum": 501
      }
    ]
  }'
```