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

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

```bash
curl -X POST \
  https://integrators.prod.api.tabsplatform.com/v3/contracts \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp — Annual Agreement 2025",
    "customerId": "{customerId}"
  }'
```

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:

```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 platform license",
    "billingStartDate": "2025-01-01",
    "isRecurring": true,
    "interval": "MONTH",
    "intervalFrequency": 1,
    "duration": 12,
    "invoiceDateStrategy": "FIRST_OF_PERIOD",
    "netPaymentTerms": 30,
    "billingType": "FLAT",
    "pricingType": "SIMPLE",
    "quantity": 0,
    "itemId": "{itemId}",
    "pricing": [
      {
        "tier": 1,
        "amount": 500.00,
        "amountType": "TOTAL_INVOICE",
        "tierMinimum": 0
      }
    ]
  }'
```

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

```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,
    "duration": 12,
    "invoiceDateStrategy": "ARREARS",
    "netPaymentTerms": 30,
    "billingType": "UNIT",
    "pricingType": "SIMPLE",
    "eventTypeId": "{eventTypeId}",
    "pricing": [
      {
        "tier": 1,
        "amount": 0.01,
        "amountType": "PER_ITEM",
        "tierMinimum": 0
      }
    ]
  }'
```

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

```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 platform license",
    "billingStartDate": "2025-01-01",
    "isRecurring": true,
    "interval": "MONTH",
    "intervalFrequency": 1,
    "duration": 12,
    "invoiceDateStrategy": "FIRST_OF_PERIOD",
    "netPaymentTerms": 30,
    "billingType": "UNIT",
    "pricingType": "SIMPLE",
    "quantity": 25,
    "pricing": [
      {
        "tier": 1,
        "amount": 50.00,
        "amountType": "PER_ITEM",
        "tierMinimum": 1
      }
    ],
    "seatConfig": {
      "isMovingMinimum": false,
      "minQuantity": 25,
      "defaultProrationPolicy": "DAY",
      "defaultTrueUpTiming": "IMMEDIATE"
    }
  }'
```