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

> **Tip**
>
> 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.

> **Note**
>
> `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
      }
    ]
  }'
```