---
title: "Create contract billing term"
method: POST
path: "/v3/contracts/{id}/billing-terms"
tags: ["Contracts"]
---

# Create contract billing term

`POST /v3/contracts/{id}/billing-terms`

## Path parameters

- `id` string, required

## Request body

- CreateBillingTermDto
  - `name` string — Line item name. Required unless `productId` is provided, in which case it is populated from the product's display name.
  - `description` string — Line item description
  - `billingStartDate` string, required — Billing start date
  - `isRecurring` boolean, required — Is recurring billing
  - `includeInArr` boolean — Whether this billing term contributes to ARR (Annual Recurring Revenue). Defaults based on billing type and interval when omitted (usage and one-time terms default to false).
  - `interval` 'NONE' | 'DAY' | 'MONTH' | 'HOUR' | 'YEAR' | 'QUARTER' | 'SEMI_MONTH' | 'WEEK', required — Interval unit
  - `intervalFrequency` number, required — Interval frequency
  - `duration` number — Number of billing periods
  - `invoiceDateStrategy` 'FIRST_OF_PERIOD' | 'LAST_OF_PERIOD' | 'ARREARS' | 'ADVANCED_DUE_START', required — Invoice date strategy
  - `netPaymentTerms` number, required — Days between invoice issue and due date
  - `quantity` number, required — Quantity; set to 0 for UNIT billingType
  - `billingType` 'UNIT' | 'FLAT', required — Billing type
  - `pricingType` 'SIMPLE' | 'TIERED' | 'VOLUME', required — Pricing type. For TIERED and VOLUME, supply 2+ pricing entries with `tier` indices that are 0-indexed and contiguous (0, 1, 2, …) and `tierMinimum` values starting at 0 and strictly increasing.
  - `eventTypeId` string — Usage event type ID
  - `itemId` string — ERP item ID for the line item
  - `productId` string, nullable — Product ID from /v3/products. When set, name/description/itemId/classId are populated from the product for any not provided on the billing term. To ensure revenue reporting accuracy, associate the billing term with a product whenever applicable.
  - `classId` string — ERP class ID
  - `departmentId` string — Department ID
  - `projectId` string — Project ID
  - `pricing` PricingTierDto[], required — Pricing tiers
    - `tier` number, required — Tier Number
    - `amount` number, required — Amount
    - `amountType` 'PER_ITEM' | 'TOTAL_INVOICE', required — Amount Type
    - `tierMinimum` number, required — Tier Minimum
  - `discount` DiscountDto
    - `type` 'PERCENTAGE' | 'FIXED' — The type of discount
    - `amount` string — The discount amount (stored as mantissa in database with exponent 0)
    - `note` string — Optional note about the discount
  - `billingTermGroupId` string — Billing term group ID. If provided, the BT joins an existing group. If omitted, a new group is created.
  - `seatConfig` SeatBasedObligationConfigDto
    - `isMovingMinimum` boolean, required — Whether we need to update minimums on a moving basis
    - `minQuantity` number, required — Minimum quantity to bill for, regardless of current # of seats
    - `defaultProrationPolicy` 'NONE' | 'DAY' | 'MONTH' | 'YEAR', required — Default proration policy
    - `defaultTrueUpTiming` 'IMMEDIATE' | 'CO_TERM', required — Default true up timing

## Response `201`

Billing term created

- object
  - `payload` object, required — Response payload, will be empty when success is false
    - `description` string — Line item description
    - `billingStartDate` string, required — Billing start date
    - `isRecurring` boolean, required — Is recurring billing
    - `includeInArr` boolean — Whether this billing term contributes to ARR (Annual Recurring Revenue). Defaults based on billing type and interval when omitted (usage and one-time terms default to false).
    - `interval` 'NONE' | 'DAY' | 'MONTH' | 'HOUR' | 'YEAR' | 'QUARTER' | 'SEMI_MONTH' | 'WEEK', required — Interval unit
    - `intervalFrequency` number, required — Interval frequency
    - `duration` number — Number of billing periods
    - `netPaymentTerms` number, required — Days between invoice issue and due date
    - `quantity` number, required — Quantity; set to 0 for UNIT billingType
    - `billingType` 'UNIT' | 'FLAT', required — Billing type
    - `pricingType` 'SIMPLE' | 'TIERED' | 'VOLUME', required — Pricing type. For TIERED and VOLUME, supply 2+ pricing entries with `tier` indices that are 0-indexed and contiguous (0, 1, 2, …) and `tierMinimum` values starting at 0 and strictly increasing.
    - `eventTypeId` string — Usage event type ID
    - `itemId` string — ERP item ID for the line item
    - `productId` string, nullable — Product ID from /v3/products. When set, name/description/itemId/classId are populated from the product for any not provided on the billing term. To ensure revenue reporting accuracy, associate the billing term with a product whenever applicable.
    - `classId` string — ERP class ID
    - `departmentId` string — Department ID
    - `projectId` string — Project ID
    - `billingTermGroupId` string — Billing term group ID. If provided, the BT joins an existing group. If omitted, a new group is created.
    - `seatConfig` SeatBasedObligationConfigDto
      - `isMovingMinimum` boolean, required — Whether we need to update minimums on a moving basis
      - `minQuantity` number, required — Minimum quantity to bill for, regardless of current # of seats
      - `defaultProrationPolicy` 'NONE' | 'DAY' | 'MONTH' | 'YEAR', required — Default proration policy
      - `defaultTrueUpTiming` 'IMMEDIATE' | 'CO_TERM', required — Default true up timing
    - `id` string, required — Billing term ID
    - `contractId` string, required — Contract ID
    - `name` string, required — Billing term name. Populated from the linked product's display name when not set on the billing term.
    - `billingEndDate` string, required — Billing end date
    - `createdAt` string, required — Created at
  - `success` boolean, required — Boolean with true=success, false=failure
  - `message` string, required — Plain-text description of the result
  - `error` IntegratorsApiError, required
    - `code` number, required — API response code
    - `message` string, required — API response message
    - `details` object — Additional details about the error

## Other responses

- `400` — Bad Request - validation failed
- `404` — Contract not found
- `500` — Internal Server Error

---

[API](https://skmtc.net/tabsplatform/apis/tabs-external-api.md) · [All operations](https://skmtc.net/tabsplatform/apis/tabs-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tabsplatform/tabs-external-api/versions/7e8885517814/schema)