Obligations

An Obligation in Tabs represents a commitment of products or services to a customer, often tied to commitment of payment. This entity serves as the foundation for generating invoices, detailing how often and how much a customer should be billed.

Obligation Object

When creating or managing an obligation, you’ll work with the following fields:

Field	Type	Description	Required
id	`string`	Unique identifier for the obligation. Generated by Tabs for existing records.	Yes (existing)
serviceStartDate	`string` (YYYY-MM-DD)	The date when the service or billing starts.	Yes
serviceEndDate	`string` (YYYY-MM-DD)	The date when the service or billing ends.	Yes
categoryId	`string`	The ID referencing the Product Category for this obligation.	Yes
billingSchedule	`BillingSchedule`	A structure defining billing terms (e.g., frequency, pricing tiers).	No (but recommended)
recognizedRevenue	`RecognizedRevenue[]`	A list of revenue entries that might be locked for historical or advanced recognition scenarios.	No

BillingSchedule

A BillingSchedule dictates how and when billing occurs for a given obligation. It includes frequency, pricing, and payment terms.

Field	Type	Description	Required
name	`string`	The line-item name (e.g., "Monthly Subscription").	Yes
description	`string`	A human-friendly description of the billed item.	No
startDate	`string` (YYYY-MM-DD)	When billing starts.	Yes
endDate	`string` (YYYY-MM-DD)	When billing ends (optional for ongoing/recurring services).	No
isArrears	`boolean`	Whether billing is in arrears (after services are rendered).	No
isRecurring	`boolean`	Indicates if billing repeats on a fixed schedule.	No
interval	`enum (DueIntervalUnit)`	Unit of the billing interval (e.g., `DAY`, `WEEK`, `MONTH`, or `YEAR`).	Yes (if recurring)
intervalFrequency	`number`	Frequency of that interval (e.g., every 1 month, every 3 months).	Yes (if recurring)
netPaymentTerms	`number`	Time between invoice issuance and due date (e.g., Net 30).	No
quantity	`number`	Quantity of items to be billed. If `billingType` is `UNIT`, this is how many units per billing cycle.	Yes (for unit-based)
billingType	`string` (`UNIT` \| `FLAT`)	Whether billing is per unit or a flat rate.	Yes
pricingType	`string` (`SIMPLE` \| `TIERED`)	Whether there’s a single price or multiple tiered prices.	Yes
eventTypeId	`string`	The usage event type ID, if this obligation is usage-based.	No
erpItemId	`string`	Maps to an item in the ERP, ensuring invoices match up in your accounting system.	No
invoiceType	`string` (`invoice` \| `bill`)	Typically `invoice`; can be `bill` if generating a remittance.	Yes
pricing	`PricingTier[]`	One or more pricing tiers, defining cost per tier.	Yes

PricingTier

PricingTier objects define how much to charge, per tier. This is essential for tier-based billing models (e.g., volume discounts).

Field	Type	Description	Required
tier	`number`	Tier number (e.g., 1 for the first tier, 2 for the second tier, etc.).	Yes
amount	`number`	Dollar amount to charge in this tier.	Yes
amountType	`string` (`PER_ITEM` \| `TOTAL_INVOICE`)	Whether this amount applies per unit or to the entire invoice line.	Yes
tierMinimum	`number`	The minimum quantity required to qualify for this tier.	Yes

RecognizedRevenue

RecognizedRevenue allows you to record and lock in revenue amounts for specific timeframes, important for compliance and accurate accounting.

Field	Type	Description	Required
timeframe	`string` (YYYY-MM-DD)	The date or period for which revenue is recognized.	Yes
total	`number`	The recognized revenue amount for that timeframe.	Yes
isLocked	`boolean`	Whether this revenue entry is locked from further edits.	Yes