> 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 contract obligation POST https://integrators.prod.api.tabsplatform.com/v3.1/contracts/{id}/obligations Content-Type: application/json Returns 202 once the change is saved. Invoices are regenerated asynchronously: poll `statusEndpoint` until the job completes. `jobId` is null when the change named no billing terms, so no regeneration was queued; `statusEndpoint` then points at the customer's invoice-generation status. Reference: https://docs.tabs.com/api-reference/contracts/integrators-api-contracts-v-31-controller-create-obligation ## Authentication - `Authorization` header (required) — API Key authentication via header ## Request ### Path parameters - `id` (string, required) — Contract Id ### Body (application/json) This endpoint expects a CreateObligationDto. - `serviceStartDate` (string, required) — Revenue Start Date - `serviceEndDate` (string, required) — Revenue End Date - `billingSchedule` (CreateBillingScheduleDto, required) — Billing Schedule - `categoryId` (string, optional) — Category Id - `discount` (DiscountDto, optional) — Discount configuration. Examples: \{ type: 'FIXED', amount: '5.00' } for a \$5.00 fixed discount, or \{ type: 'PERCENTAGE', amount: '0.10' } for a 10% percentage discount - `seatConfig` (SeatBasedObligationConfigDto, optional) — Seat-based obligation configuration ## Response ### 202 The obligation, and the invoice regeneration job - `payload` (ObligationWriteResponseDto, required) — Response payload, will be empty when success is false - `success` (boolean, required) — Boolean with true=success, false=failure - `message` (string, required) — Plain-text description of the result - `error` (IntegratorsApiError, optional) — json element with any error messages or warnings ## Errors ### 400 Bad Request Error Invalid request body - `any` ### 404 Not Found Error Contract not found - `any` ## Types ### CreateBillingScheduleDto - `startDate` (string, required) — Billing Start Date - `isRecurring` (boolean, required) — Is Recurring - `interval` (enum, required) — Type of recurring interval. - Allowed values: `NONE`, `DAY`, `WEEK`, `MONTH`, `SEMI_MONTH`, `YEAR` - `intervalFrequency` (double, required) — Frequency of recurring interval to invoice - `netPaymentTerms` (double, required) — Time between issue and due date - `quantity` (double, required) — Quantity; set to 0 for UNIT billingType - `billingType` (enum, required) — Billing Type - Allowed values: `UNIT`, `FLAT` - `pricingType` (enum, required) — Single, multiple, or volume-based pricing tiers - Allowed values: `SIMPLE`, `TIERED`, `VOLUME` - `invoiceType` (enum, required) — INVOICE or BILL for remittance. Use INVOICE for all instances - Allowed values: `INVOICE`, `BILL` - `pricing` (list of PricingTierDto, required) — Pricing tiers - `description` (string, optional) — Line Item Description - `duration` (double, optional, default: 0) — Billing Duration - `invoiceDateStrategy` (enum, optional) — Strategy for determining when to send invoices. Either this field OR isArrears must be provided, but not both. FIRST_OF_PERIOD (invoice at start of billing period), LAST_OF_PERIOD (invoice at end of billing period), ARREARS (invoice after service delivery), ADVANCED_DUE_START (invoice date at start of billing period minus netPaymentTerms days, due start of service), OFFSET_FROM_PERIOD_START / OFFSET_FROM_PERIOD_END (invoice date at period start/end plus invoiceDateOffsetDays). - Allowed values: `FIRST_OF_PERIOD`, `LAST_OF_PERIOD`, `ARREARS`, `ADVANCED_DUE_START`, `OFFSET_FROM_PERIOD_START`, `OFFSET_FROM_PERIOD_END` - `invoiceDateOffsetDays` (double, optional) — Days to offset the invoice date from the period start (OFFSET_FROM_PERIOD_START) or period end (OFFSET_FROM_PERIOD_END). Required for those strategies and not allowed for FIRST_OF_PERIOD, LAST_OF_PERIOD, ARREARS, or ADVANCED_DUE_START. Integer from -365 to 365. - `includeInArr` (boolean, optional) — 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). - `eventTypeId` (string, optional) — Usage Event Type Id - `itemId` (string, optional) — The item in the ERP that the line items will belong to - `productId` (string, optional, nullable) — Product ID from /v3/products that links this billing term to an entry in the merchant's product catalog. To ensure revenue reporting accuracy, associate the billing term with a product whenever applicable. - `classId` (string, optional) — Class Id - `departmentId` (string, optional) — Department Id - `projectId` (string, optional) — Project Id - `name` (string, optional) — Line item name. Required unless productId is provided, in which case it is populated from the product's display name. - `isArrears` (boolean, optional, deprecated) — Is Arrears (DEPRECATED: Use invoiceDateStrategy instead). Either this field OR invoiceDateStrategy must be provided, but not both. ### DiscountDto - `type` (enum, optional) — The type of discount - Allowed values: `PERCENTAGE`, `FIXED` - `amount` (string, optional) — The discount amount (stored as mantissa in database with exponent 0) - `note` (string, optional) — Optional note about the discount ### SeatBasedObligationConfigDto - `isMovingMinimum` (boolean, required) — Whether we need to update minimums on a moving basis - `minQuantity` (double, required) — Minimum quantity to bill for, regardless of current # of seats - `defaultProrationPolicy` (enum, required) — Default proration policy - Allowed values: `NONE`, `DAY`, `MONTH`, `YEAR` - `defaultTrueUpTiming` (enum, required) — Default true up timing - Allowed values: `IMMEDIATE`, `CO_TERM` ### ObligationWriteResponseDto - `id` (string, required) — Obligation Id - `contractId` (string, required) — Contract Id - `serviceStartDate` (string, required) — Revenue Start Date - `serviceEndDate` (string, required) — Revenue End Date - `billingSchedule` (BillingScheduleDto, required) — Billing Schedule - `revenueSchedule` (RevenueScheduleDto, required) — Revenue Schedule - `jobId` (string, required, nullable) — Invoice regeneration job ID. Null when the change named no billing terms, so no regeneration was queued - `statusEndpoint` (string, required) — Where to check status: /v3/jobs/\{jobId} when a regeneration was queued, or /v3/customers/\{customerId}/invoice-generation-status when it was not - `categoryId` (string, optional) — Category Id - `discount` (DiscountDto, optional) — Discount configuration. Examples: \{ type: 'FIXED', amount: '5.00' } for a \$5.00 fixed discount, or \{ type: 'PERCENTAGE', amount: '0.10' } for a 10% percentage discount - `seatConfig` (SeatBasedObligationConfigDto, optional) — Seat-based obligation configuration ### IntegratorsApiError - `code` (double, required) — API response code - `message` (string, required) — API response message - `errorCode` (string, optional) — Machine-readable error code - `details` (IntegratorsApiErrorDetails, optional) — Additional details about the error ### PricingTierDto - `tier` (double, required) — Tier Number - `amount` (double, required) — Amount - `amountType` (enum, required) — Amount Type - Allowed values: `PER_ITEM`, `TOTAL_INVOICE` - `tierMinimum` (double, required) — Tier Minimum - `name` (string, optional) — Tier name ### BillingScheduleDto - `id` (string, required) — Billing Term Id - `name` (string, required) — Line Item Name - `startDate` (string, required) — Billing Start Date - `endDate` (string, required) — Billing End Date - `isRecurring` (boolean, required) — Is Recurring - `interval` (enum, required) — Type of recurring interval. - Allowed values: `NONE`, `DAY`, `WEEK`, `MONTH`, `SEMI_MONTH`, `YEAR` - `intervalFrequency` (double, required) — Frequency of recurring interval to invoice - `netPaymentTerms` (double, required) — Time between issue and due date - `quantity` (double, required) — Quantity; set to 0 for UNIT billingType - `billingType` (enum, required) — Billing Type - Allowed values: `UNIT`, `FLAT` - `pricingType` (enum, required) — Single, multiple, or volume-based pricing tiers - Allowed values: `SIMPLE`, `TIERED`, `VOLUME` - `eventTypeName` (string, required, nullable) — Usage Event Type name - `invoiceType` (enum, required) — INVOICE or BILL for remittance. Use INVOICE for all instances - Allowed values: `INVOICE`, `BILL` - `pricing` (list of PricingTierDto, required) — Pricing tiers - `description` (string, optional) — Line Item Description - `duration` (double, optional, default: 0) — Billing Duration - `invoiceDateStrategy` (enum, optional) — Strategy for determining when to send invoices. Either this field OR isArrears must be provided, but not both. FIRST_OF_PERIOD (invoice at start of billing period), LAST_OF_PERIOD (invoice at end of billing period), ARREARS (invoice after service delivery), ADVANCED_DUE_START (invoice date at start of billing period minus netPaymentTerms days, due start of service), OFFSET_FROM_PERIOD_START / OFFSET_FROM_PERIOD_END (invoice date at period start/end plus invoiceDateOffsetDays). - Allowed values: `FIRST_OF_PERIOD`, `LAST_OF_PERIOD`, `ARREARS`, `ADVANCED_DUE_START`, `OFFSET_FROM_PERIOD_START`, `OFFSET_FROM_PERIOD_END` - `invoiceDateOffsetDays` (double, optional) — Days to offset the invoice date from the period start (OFFSET_FROM_PERIOD_START) or period end (OFFSET_FROM_PERIOD_END). Required for those strategies and not allowed for FIRST_OF_PERIOD, LAST_OF_PERIOD, ARREARS, or ADVANCED_DUE_START. Integer from -365 to 365. - `includeInArr` (boolean, optional) — 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). - `eventTypeId` (string, optional) — Usage Event Type Id - `itemId` (string, optional) — The item in the ERP that the line items will belong to - `productId` (string, optional, nullable) — Product ID from /v3/products that links this billing term to an entry in the merchant's product catalog. To ensure revenue reporting accuracy, associate the billing term with a product whenever applicable. - `classId` (string, optional) — Class Id - `departmentId` (string, optional) — Department Id - `projectId` (string, optional) — Project Id - `isArrears` (boolean, optional, deprecated) — Is Arrears (DEPRECATED: Use invoiceDateStrategy instead). Either this field OR invoiceDateStrategy must be provided, but not both. ### RevenueScheduleDto - `recognizedRevenue` (list of RecognizedRevenueDto, required) — Recognized Revenue in each month - `categoryId` (string, optional) — Category Id ### IntegratorsApiErrorDetails Additional details about the error ### RecognizedRevenueDto - `timeframe` (string, required) — Timeframe - `total` (double, required) — Total - `booksClosed` (boolean, required) — Books closed ## Examples **Request** ```json { "serviceStartDate": "2024-01-01", "serviceEndDate": "2024-01-01", "billingSchedule": { "startDate": "2024-01-01", "isRecurring": true, "interval": "MONTH", "intervalFrequency": 1, "netPaymentTerms": 1, "quantity": 1, "billingType": "UNIT", "pricingType": "SIMPLE", "invoiceType": "INVOICE", "pricing": [ { "tier": 1, "amount": 100, "amountType": "PER_ITEM", "tierMinimum": 0 } ] } } ``` **Response** ```json { "payload": { "id": "123e4567-e89b-12d3-a456-426614174000", "contractId": "123e4567-e89b-12d3-a456-426614174000", "serviceStartDate": "2024-01-01", "serviceEndDate": "2024-01-01", "billingSchedule": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Line Item Name", "startDate": "2024-01-01", "endDate": "2024-01-01", "isRecurring": true, "interval": "MONTH", "intervalFrequency": 1, "netPaymentTerms": 1, "quantity": 1, "billingType": "UNIT", "pricingType": "SIMPLE", "eventTypeName": "API Calls", "invoiceType": "INVOICE", "pricing": [ { "tier": 1, "amount": 100, "amountType": "PER_ITEM", "tierMinimum": 0 } ], "description": "Line Item Description", "duration": 1, "invoiceDateStrategy": "FIRST_OF_PERIOD", "invoiceDateOffsetDays": 5, "includeInArr": true, "eventTypeId": "123e4567-e89b-12d3-a456-426614174000", "itemId": "123e4567-e89b-12d3-a456-426614174000", "productId": "123e4567-e89b-12d3-a456-426614174000", "classId": "123e4567-e89b-12d3-a456-426614174000", "departmentId": "123e4567-e89b-12d3-a456-426614174000", "projectId": "123e4567-e89b-12d3-a456-426614174000", "isArrears": false }, "revenueSchedule": { "recognizedRevenue": [ { "timeframe": "2024-01", "total": 1000, "booksClosed": false } ], "categoryId": "123e4567-e89b-12d3-a456-426614174000" }, "jobId": "wf-8f3c1e20-…", "statusEndpoint": "/v3/jobs/wf-8f3c1e20-…", "categoryId": "123e4567-e89b-12d3-a456-426614174000", "discount": { "type": "FIXED", "amount": "5.00" }, "seatConfig": { "isMovingMinimum": false, "minQuantity": 0, "defaultProrationPolicy": "NONE", "defaultTrueUpTiming": "IMMEDIATE" } }, "success": true, "message": "string", "error": { "code": 1.1, "message": "string", "errorCode": "string", "details": {} } } ``` **SDK Code** ```python import requests url = "https://integrators.prod.api.tabsplatform.com/v3.1/contracts/123e4567-e89b-12d3-a456-426614174000/obligations" payload = { "serviceStartDate": "2024-01-01", "serviceEndDate": "2024-01-01", "billingSchedule": { "startDate": "2024-01-01", "isRecurring": True, "interval": "MONTH", "intervalFrequency": 1, "netPaymentTerms": 1, "quantity": 1, "billingType": "UNIT", "pricingType": "SIMPLE", "invoiceType": "INVOICE", "pricing": [ { "tier": 1, "amount": 100, "amountType": "PER_ITEM", "tierMinimum": 0 } ] } } headers = { "Authorization": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://integrators.prod.api.tabsplatform.com/v3.1/contracts/123e4567-e89b-12d3-a456-426614174000/obligations'; const options = { method: 'POST', headers: {Authorization: '', 'Content-Type': 'application/json'}, body: '{"serviceStartDate":"2024-01-01","serviceEndDate":"2024-01-01","billingSchedule":{"startDate":"2024-01-01","isRecurring":true,"interval":"MONTH","intervalFrequency":1,"netPaymentTerms":1,"quantity":1,"billingType":"UNIT","pricingType":"SIMPLE","invoiceType":"INVOICE","pricing":[{"tier":1,"amount":100,"amountType":"PER_ITEM","tierMinimum":0}]}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://integrators.prod.api.tabsplatform.com/v3.1/contracts/123e4567-e89b-12d3-a456-426614174000/obligations" payload := strings.NewReader("{\n \"serviceStartDate\": \"2024-01-01\",\n \"serviceEndDate\": \"2024-01-01\",\n \"billingSchedule\": {\n \"startDate\": \"2024-01-01\",\n \"isRecurring\": true,\n \"interval\": \"MONTH\",\n \"intervalFrequency\": 1,\n \"netPaymentTerms\": 1,\n \"quantity\": 1,\n \"billingType\": \"UNIT\",\n \"pricingType\": \"SIMPLE\",\n \"invoiceType\": \"INVOICE\",\n \"pricing\": [\n {\n \"tier\": 1,\n \"amount\": 100,\n \"amountType\": \"PER_ITEM\",\n \"tierMinimum\": 0\n }\n ]\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://integrators.prod.api.tabsplatform.com/v3.1/contracts/123e4567-e89b-12d3-a456-426614174000/obligations") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"serviceStartDate\": \"2024-01-01\",\n \"serviceEndDate\": \"2024-01-01\",\n \"billingSchedule\": {\n \"startDate\": \"2024-01-01\",\n \"isRecurring\": true,\n \"interval\": \"MONTH\",\n \"intervalFrequency\": 1,\n \"netPaymentTerms\": 1,\n \"quantity\": 1,\n \"billingType\": \"UNIT\",\n \"pricingType\": \"SIMPLE\",\n \"invoiceType\": \"INVOICE\",\n \"pricing\": [\n {\n \"tier\": 1,\n \"amount\": 100,\n \"amountType\": \"PER_ITEM\",\n \"tierMinimum\": 0\n }\n ]\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://integrators.prod.api.tabsplatform.com/v3.1/contracts/123e4567-e89b-12d3-a456-426614174000/obligations") .header("Authorization", "") .header("Content-Type", "application/json") .body("{\n \"serviceStartDate\": \"2024-01-01\",\n \"serviceEndDate\": \"2024-01-01\",\n \"billingSchedule\": {\n \"startDate\": \"2024-01-01\",\n \"isRecurring\": true,\n \"interval\": \"MONTH\",\n \"intervalFrequency\": 1,\n \"netPaymentTerms\": 1,\n \"quantity\": 1,\n \"billingType\": \"UNIT\",\n \"pricingType\": \"SIMPLE\",\n \"invoiceType\": \"INVOICE\",\n \"pricing\": [\n {\n \"tier\": 1,\n \"amount\": 100,\n \"amountType\": \"PER_ITEM\",\n \"tierMinimum\": 0\n }\n ]\n }\n}") .asString(); ``` ```php request('POST', 'https://integrators.prod.api.tabsplatform.com/v3.1/contracts/123e4567-e89b-12d3-a456-426614174000/obligations', [ 'body' => '{ "serviceStartDate": "2024-01-01", "serviceEndDate": "2024-01-01", "billingSchedule": { "startDate": "2024-01-01", "isRecurring": true, "interval": "MONTH", "intervalFrequency": 1, "netPaymentTerms": 1, "quantity": 1, "billingType": "UNIT", "pricingType": "SIMPLE", "invoiceType": "INVOICE", "pricing": [ { "tier": 1, "amount": 100, "amountType": "PER_ITEM", "tierMinimum": 0 } ] } }', 'headers' => [ 'Authorization' => '', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://integrators.prod.api.tabsplatform.com/v3.1/contracts/123e4567-e89b-12d3-a456-426614174000/obligations"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"serviceStartDate\": \"2024-01-01\",\n \"serviceEndDate\": \"2024-01-01\",\n \"billingSchedule\": {\n \"startDate\": \"2024-01-01\",\n \"isRecurring\": true,\n \"interval\": \"MONTH\",\n \"intervalFrequency\": 1,\n \"netPaymentTerms\": 1,\n \"quantity\": 1,\n \"billingType\": \"UNIT\",\n \"pricingType\": \"SIMPLE\",\n \"invoiceType\": \"INVOICE\",\n \"pricing\": [\n {\n \"tier\": 1,\n \"amount\": 100,\n \"amountType\": \"PER_ITEM\",\n \"tierMinimum\": 0\n }\n ]\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "", "Content-Type": "application/json" ] let parameters = [ "serviceStartDate": "2024-01-01", "serviceEndDate": "2024-01-01", "billingSchedule": [ "startDate": "2024-01-01", "isRecurring": true, "interval": "MONTH", "intervalFrequency": 1, "netPaymentTerms": 1, "quantity": 1, "billingType": "UNIT", "pricingType": "SIMPLE", "invoiceType": "INVOICE", "pricing": [ [ "tier": 1, "amount": 100, "amountType": "PER_ITEM", "tierMinimum": 0 ] ] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://integrators.prod.api.tabsplatform.com/v3.1/contracts/123e4567-e89b-12d3-a456-426614174000/obligations")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```