Tabs Contracts API
The Contracts API from Tabs — 17 operation(s) for contracts.
OpenAPI Specification
openapi: 3.0.0
info:
title: Tabs External Billing Terms Contracts API
description: ''
version: 1.0.0
contact: {}
x-apievangelist:
generated: '2026-07-21'
method: searched
source: https://docs.tabsplatform.com/reference (OpenAPI definitions embedded per-operation in the ReadMe reference pages, merged; index at https://docs.tabsplatform.com/llms.txt)
source_pages: 93
servers:
- url: https://integrators.prod.api.tabsplatform.com
security:
- custom-header: []
tags:
- name: Contracts
paths:
/v3/contracts:
get:
operationId: IntegratorsApiContractsv3Controller_getContracts
parameters:
- name: page
required: true
in: query
description: Page Number
schema:
default: 1
type: number
- name: limit
required: true
in: query
description: Number of items to return
schema:
default: 50
type: number
- name: filter
required: false
in: query
description: 'Supported items for filter: name, externalIds.externalId, externalIds.sourceType, source, status, customerId, createdAt, lastUpdatedAt. Date format for createdAt and lastUpdatedAt: YYYY-MM-DD'
schema:
type: string
responses:
'200':
description: Get all Contracts by filter
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/IntegratorsApiResponse'
- type: object
properties:
payload:
allOf:
- $ref: '#/components/schemas/PaginatedResponseDTO'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ContractsV3Dto'
limit:
type: number
totalItems:
type: number
currentPage:
type: number
summary: List contracts
tags:
- Contracts
post:
operationId: IntegratorsApiContractsv3Controller_createContract
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateContractV3Dto'
responses:
'201':
description: Created contract
content:
application/json:
schema:
$ref: '#/components/schemas/ContractsV3Dto'
'400':
description: Invalid request body
'500':
description: Internal server error
summary: Create contract
tags:
- Contracts
/v3/contracts/{id}:
get:
operationId: IntegratorsApiContractsv3Controller_getContractById
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
responses:
'200':
description: The contract
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/IntegratorsApiResponse'
- properties:
payload:
allOf:
- $ref: '#/components/schemas/ContractsV3Dto'
'400':
description: Contract is deleted
'404':
description: Contract not found
summary: Get contract by ID
tags:
- Contracts
patch:
operationId: IntegratorsApiContractsv3Controller_updateContract
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateContractV3Dto'
responses:
'200':
description: Contract updated successfully
'404':
description: Contract not found
'500':
description: Internal server error
summary: Update contract
tags:
- Contracts
/v3/contracts/{id}/file:
post:
operationId: IntegratorsApiContractsv3Controller_uploadContractFile
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
- name: shouldProcess
required: false
in: query
description: Whether to trigger contract processing after file upload. Defaults to true.
schema:
type: boolean
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
responses:
'200':
description: Contract file was replaced successfully
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/IntegratorsApiResponse'
- properties:
payload:
allOf:
- $ref: '#/components/schemas/ContractsV3Dto'
summary: Upload contract file
tags:
- Contracts
get:
operationId: IntegratorsApiContractsv3Controller_getContractFile
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
responses:
'200':
description: PDF file download
content:
application/pdf:
schema:
type: string
format: binary
'500':
description: Internal server error or contract has no file
summary: Download contract file
tags:
- Contracts
/v3/contracts/{id}/obligations:
post:
operationId: IntegratorsApiContractsv3Controller_createObligation
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateObligationDto'
responses:
'201':
description: The obligation
content:
application/json:
schema:
$ref: '#/components/schemas/ObligationDto'
'400':
description: Invalid request body
summary: Create contract obligation
tags:
- Contracts
/v3/contracts/{id}/obligations/{obligationId}:
get:
operationId: IntegratorsApiContractsv3Controller_getObligation
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
- name: obligationId
required: true
in: path
description: Obligation Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
responses:
'200':
description: The obligation
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/IntegratorsApiResponse'
- properties:
payload:
allOf:
- $ref: '#/components/schemas/ObligationDto'
'404':
description: Obligation not found
summary: Get contract obligation by ID
tags:
- Contracts
delete:
operationId: IntegratorsApiContractsv3Controller_deleteObligation
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
- name: obligationId
required: true
in: path
description: Obligation Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
responses:
'200':
description: Deleted obligation
'400':
description: Obligation not found
'500':
description: Internal server error
summary: Delete contract obligation
tags:
- Contracts
/v3/contracts/{id}/actions:
post:
operationId: IntegratorsApiContractsv3Controller_contractActions
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
requestBody:
required: true
description: 'For Rillet merchants only: Close Date is required when marking contracts as processed.'
content:
application/json:
schema:
$ref: '#/components/schemas/ContractActionDto'
examples:
valid1:
summary: Mark as processed
value:
action: MARK_AS_PROCESSED
valid2:
summary: Mark as deleted
value:
action: MARK_AS_DELETED
responses:
'200':
description: Contract actions executed successfully
'400':
description: Invalid request body
summary: Perform contract action
tags:
- Contracts
/v3/contracts/{id}/obligation/{obligationId}:
patch:
operationId: IntegratorsApiContractsv3Controller_updateObligation
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
- name: obligationId
required: true
in: path
description: Obligation Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateObligationDto'
responses:
'200':
description: Obligation updated successfully
'404':
description: Obligation not found
'500':
description: Internal server error
summary: Update contract obligation
tags:
- Contracts
/v3/contracts/{id}/obligation/{obligationId}/custom-revenue:
post:
operationId: IntegratorsApiContractsv3Controller_upsertCustomRevenue
parameters:
- name: id
required: true
in: path
description: Contract id
schema:
type: string
- name: obligationId
required: true
in: path
description: Obligation id
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CustomRevenue'
responses:
'200':
description: Upsert custom revenue
'400':
description: Bad request body, e.g. invalid timeframe
'404':
description: Contract or obligation not found
'500':
description: Internal server error
summary: Upsert obligation custom revenue
tags:
- Contracts
/v3/contracts/{id}/billing-term-groups:
get:
operationId: IntegratorsApiContractsv3Controller_getBillingTermGroups
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
- name: page
required: true
in: query
description: Page Number
schema:
default: 1
type: number
- name: limit
required: true
in: query
description: Number of items to return
schema:
default: 50
type: number
- name: filter
required: false
in: query
description: "\n Supported items for filter: createdAt, updatedAt\n\n Dates should be in YYYY-MM-DD format\n "
schema:
type: string
responses:
'200':
description: Billing term groups for the contract
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/IntegratorsApiResponse'
- properties:
payload:
allOf:
- $ref: '#/components/schemas/PaginatedResponseDTO'
- properties:
data:
type: array
items:
$ref: '#/components/schemas/BillingTermGroupDto'
limit:
type: number
totalItems:
type: number
currentPage:
type: number
'400':
description: Invalid contract ID or performance obligation features not enabled for this merchant
'404':
description: Contract not found
'500':
description: Internal Server Error
summary: List contract billing term groups
tags:
- Contracts
/v3/contracts/{id}/billing-term-groups/{groupId}:
delete:
operationId: IntegratorsApiContractsv3Controller_deleteBillingTermGroup
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
- name: groupId
required: true
in: path
description: Billing Term Group Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
responses:
'200':
description: Billing term group and associated entities deleted successfully
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/IntegratorsApiResponse'
- properties:
payload:
type: object
properties:
message:
type: string
'400':
description: Invalid contract/group ID or performance obligation features not enabled for this merchant
'404':
description: Contract or billing term group not found
'500':
description: Internal Server Error
summary: Delete contract billing term group
tags:
- Contracts
/v3/contracts/{id}/performance-obligations:
get:
operationId: IntegratorsApiContractsv3Controller_getPerformanceObligationsWithRevenue
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
- name: billingTermGroupId
required: false
in: query
description: Optional billing term group ID to filter results
schema:
type: string
- name: page
required: true
in: query
description: Page Number
schema:
default: 1
type: number
- name: limit
required: true
in: query
description: Number of items to return
schema:
default: 50
type: number
- name: filter
required: false
in: query
description: "\n Supported items for filter: createdAt, updatedAt\n\n Dates should be in YYYY-MM-DD format\n "
schema:
type: string
responses:
'200':
description: Performance obligations with recognized revenue for the contract
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/IntegratorsApiResponse'
- properties:
payload:
allOf:
- $ref: '#/components/schemas/PaginatedResponseDTO'
- properties:
data:
type: array
items:
$ref: '#/components/schemas/PerformanceObligationDetailResponseDto'
limit:
type: number
totalItems:
type: number
currentPage:
type: number
totalTransactionPrice:
type: number
'400':
description: Performance obligation features not enabled for this merchant
'404':
description: Contract not found
'500':
description: Internal Server Error
summary: List contract performance obligations
tags:
- Contracts
post:
operationId: IntegratorsApiContractsv3Controller_batchSavePobsForContract
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
requestBody:
required: true
description: Batch create, update, and delete performance obligations scoped to a billing term group
content:
application/json:
schema:
$ref: '#/components/schemas/BatchSavePobsForContractDto'
responses:
'200':
description: Batch save completed successfully
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/IntegratorsApiResponse'
- properties:
payload:
$ref: '#/components/schemas/BatchSavePerformanceObligationsResponseDto'
'400':
description: Validation error or performance obligation features not enabled
'404':
description: Contract not found
'500':
description: Internal Server Error
summary: Bulk save contract performance obligations
tags:
- Contracts
/v3/contracts/{id}/performance-obligations/{pobId}:
patch:
operationId: IntegratorsApiContractsv3Controller_updatePerformanceObligation
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
- name: pobId
required: true
in: path
description: Performance Obligation Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
requestBody:
required: true
description: Fields to update on the performance obligation
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePerformanceObligationForContractDto'
responses:
'200':
description: Performance obligation updated successfully
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/IntegratorsApiResponse'
- properties:
payload:
$ref: '#/components/schemas/PerformanceObligationDetailResponseDto'
'400':
description: Validation error or performance obligation features not enabled
'404':
description: Contract or performance obligation not found
'500':
description: Internal Server Error
summary: Update contract performance obligation
tags:
- Contracts
/v3/contracts/{id}/billing-terms:
get:
operationId: IntegratorsApiContractsv3Controller_getBillingTerms
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
- name: billingTermGroupId
required: false
in: query
description: Optional billing term group (BTG) ID to filter by
schema:
type: string
- name: page
required: true
in: query
description: Page Number
schema:
default: 1
type: number
- name: limit
required: true
in: query
description: Number of items to return
schema:
default: 50
type: number
responses:
'200':
description: Billing terms for the contract
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/IntegratorsApiResponse'
- properties:
payload:
allOf:
- $ref: '#/components/schemas/PaginatedResponseDTO'
- properties:
data:
type: array
items:
$ref: '#/components/schemas/GetBillingTermItemDto'
limit:
type: number
totalItems:
type: number
currentPage:
type: number
'404':
description: Contract not found
'500':
description: Internal Server Error
summary: List contract billing terms
tags:
- Contracts
post:
operationId: IntegratorsApiContractsv3Controller_createBillingTerm
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBillingTermDto'
responses:
'201':
description: Billing term created
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/IntegratorsApiResponse'
- properties:
payload:
$ref: '#/components/schemas/BillingTermResponseDto'
'400':
description: Bad Request - validation failed
'404':
description: Contract not found
'500':
description: Internal Server Error
summary: Create contract billing term
tags:
- Contracts
/v3/contracts/{id}/billing-terms/{billingTermId}:
patch:
operationId: IntegratorsApiContractsv3Controller_patchBillingTerm
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
- name: billingTermId
required: true
in: path
description: Billing Term Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchBillingTermDto'
responses:
'200':
description: Billing term updated
'400':
description: Bad Request - validation failed
'404':
description: Contract or billing term not found
'500':
description: Internal Server Error
summary: Update contract billing term
tags:
- Contracts
delete:
operationId: IntegratorsApiContractsv3Controller_deleteBillingTerm
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
- name: billingTermId
required: true
in: path
description: Billing Term Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
responses:
'200':
description: Billing term deleted
'404':
description: Contract or billing term not found
'409':
description: 'Cannot delete: a POB with matching event type exists in the group'
'500':
description: Internal Server Error
summary: Delete contract billing term
tags:
- Contracts
/v3.1/contracts/{id}/obligation/{obligationId}:
patch:
operationId: IntegratorsApiContractsV31Controller_updateObligation
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
- name: obligationId
required: true
in: path
description: Obligation Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateObligationDto'
responses:
'200':
description: Obligation updated successfully
'404':
description: Obligation not found
'500':
description: Internal server error
summary: Update contract obligation
tags:
- Contracts
/v3/contracts/deleted:
get:
operationId: IntegratorsApiContractsv3Controller_getDeletedContracts
parameters:
- name: page
required: true
in: query
description: Page Number
schema:
default: 1
type: number
- name: limit
required: true
in: query
description: Number of items to return
schema:
default: 50
type: number
- name: filter
required: false
in: query
description: 'Supported items for filter: name, externalIds.externalId, externalIds.sourceType, source, status, customerId, createdAt, lastUpdatedAt, deletedAt. Date format for createdAt, lastUpdatedAt, and deletedAt: YYYY-MM-DD'
schema:
type: string
responses:
'200':
description: Get all deleted Contracts by filter, sorted by deletedAt desc
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/IntegratorsApiResponse'
- type: object
properties:
payload:
allOf:
- $ref: '#/components/schemas/PaginatedResponseDTO'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ContractsV3Dto'
limit:
type: number
totalItems:
type: number
currentPage:
type: number
summary: List deleted contracts
tags:
- Contracts
/v3/contracts/{id}/billing-term-groups/{groupId}/event-type:
patch:
operationId: IntegratorsApiContractsv3Controller_changeBillingTermGroupEventType
parameters:
- name: id
required: true
in: path
description: Contract Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
- name: groupId
required: true
in: path
description: Billing Term Group Id
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChangeBillingTermGroupEventTypeDto'
responses:
'200':
description: Event type changed for the selected billing terms and performance obligations within the group; any rows not listed in the request are left untouched. The change is applied atomically and is only accepted if the group's event types stay in sync afterward.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/IntegratorsApiResponse'
- properties:
payload:
$ref: '#/components/schemas/ChangeBillingTermGroupEventTypeResponseDto'
'400':
description: Invalid request, or a provided BT/POB does not belong to the group
'404':
description: Contract, billing term group, or target event type not found
'409':
description: Change would break the event-type invariant for the group
'500':
description: Internal Server Error
summary: Change event type for selected billing terms and POBs in a group
tags:
- Contracts
components:
schemas:
GetBillingTermItemDto:
type: object
properties:
billingTermId:
type: string
description: Billing term ID
format: uuid
contractId:
type: string
description: Contract ID
format: uuid
name:
type: string
description: Billing term name
description:
type: string
description: Billing term description
nullable: true
itemId:
type: string
description: ERP item ID
format: uuid
nullable: true
productId:
type: string
description: Product ID from /v3/products. To ensure revenue reporting accuracy, associate the billing term with a product whenever applicable.
format: uuid
nullable: true
billingStartDate:
type: string
description: Billing start date
billingEndDate:
type: string
description: Billing end date
quantity:
type: number
description: Quantity; 0 for UNIT billingType
example: 1
duration:
type: number
description: Number of billing periods (0 = open-ended / not set)
example: 12
intervalFrequency:
type: number
description: Interval frequency
interval:
type: string
description: Interval unit
enum:
- NONE
- DAY
- MONTH
- HOUR
- YEAR
- QUARTER
- SEMI_MONTH
- WEEK
example: MONTH
nullable: true
invoiceDateStrategy:
type: string
description: Invoice date strategy
enum:
- FIRST_OF_PERIOD
- LAST_OF_PERIOD
- ARREARS
- ADVANCED_DUE_START
example: FIRST_OF_PERIOD
netPaymentTerms:
type: number
description: Days between invoice issue and due date
example: 30
nullable: true
billingType:
type: string
description: Billing type
example: FLAT
enum:
- UNIT
- FLAT
pricingType:
type: string
description: Pricing type
example: SIMPLE
enum:
- SIMPLE
- TIE
# --- truncated at 32 KB (83 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tabs/refs/heads/main/openapi/tabs-contracts-api-openapi.yml