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

# Get commitment by ID

GET https://integrators.prod.api.tabsplatform.com/v3/commitments/{commitmentId}

Reference: https://docs.tabs.com/api-reference/commitments/integrators-api-commitments-controller-get-commitment-by-id

## Authentication

- `Authorization` header (required) — API Key authentication via header

## Request

### Path parameters

- `commitmentId` (string, required) — Commitment ID

## Response

### 200

Get commitment by ID with breakdown by commitment period and overage details

- `payload` (CommitmentDto, 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

### 404 Not Found Error

Commitment not found

- `any`

### 500 Internal Server Error

Internal Server Error

- `any`

## Types

### CommitmentDto

- `id` (string, required) — Commitment ID
- `contractId` (string, required) — Contract ID this commitment belongs to
- `customerId` (string, required) — Customer ID for this commitment's contract
- `prepaidEnabled` (boolean, required) — Whether prepaid is enabled
- `commitmentValue` (string, required) — Commitment value
- `commitmentUnitType` (enum, required) — Commitment unit type
  - Allowed values: `DOLLARS`, `UNITS`
- `eventTypesIncluded` (list of string, required) — List of event types included in this commitment
- `currentCumulative` (MetricsDto, required) — Current cumulative usage metrics
- `createdAt` (string, required) — Created at timestamp
- `updatedAt` (string, required) — Updated at timestamp
- `prepaidValue` (string, optional) — Prepaid value if prepaid is enabled
- `commitmentStartDate` (string, optional) — Commitment start date
- `commitmentEndDate` (string, optional) — Commitment end date (inclusive — the last day of the commitment)
- `commitmentPeriodInterval` (enum, optional) — Commitment period interval
  - Allowed values: `DAILY`, `WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMI_ANNUAL`, `YEARLY`
- `commitmentCustomInterval` (string, optional) — Custom interval specification
- `pricePriority` (enum, optional) — Price priority for this commitment
  - Allowed values: `LOW`, `HIGH`
- `prepaymentScheduleType` (enum, optional) — Prepayment schedule type
  - Allowed values: `FULL_UPFRONT`, `PER_COMMITMENT_PERIOD`, `SPLIT_ACROSS_BILLING_PERIODS`
- `totals` (TotalsDto, optional) — Total amounts for overages and true-ups
- `periods` (list of CommitmentPeriodDto, optional) — List of commitment periods with usage data
- `deletedAt` (string, optional) — Soft delete timestamp (null if not deleted)
- `trueUpBehavior` (enum, optional) — True-up behavior for the commitment (commitments-v2)
  - Allowed values: `DEFAULT`, `NEVER`
- `schedules` (list of ScheduleDto, optional) — Nested schedule/step structure. Present when the commitment has a schedule/step tree. The top-level fields above are sourced from the parent commitment (schedule 0 / step 0) for back-compat.

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

### MetricsDto

- `amount` (string, required) — Amount
- `units` (string, required) — Units/quantity

### TotalsDto

### CommitmentPeriodDto

- `periodId` (string, required) — Commitment period ID
- `periodDate` (string, required) — Period start date
- `amounts` (PeriodAmountsDto, required) — Amounts for this period
- `eventTypes` (list of EventTypeOverageDto, required) — Breakdown of usage by event type
- `createdAt` (string, required) — Created at timestamp
- `updatedAt` (string, required) — Updated at timestamp
- `finalizedAt` (string, optional, nullable) — Timestamp when the period was finalized; null if not yet finalized
- `lastCalculatedAt` (string, optional) — Last time the period was calculated

### ScheduleDto

- `id` (string, required) — Schedule ID
- `sequence` (double, required) — Dense schedule ordinal within the commitment (0..N-1)
- `startDate` (string, required) — Schedule start date
- `endDate` (string, required) — Schedule end date (inclusive — the last day of the schedule)
- `steps` (list of StepDto, required) — Steps within this schedule (dense, ordered)
- `commitmentInterval` (enum, optional) — Commitment period interval for this schedule
  - Allowed values: `DAILY`, `WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMI_ANNUAL`, `YEARLY`
- `prepaymentScheduleType` (enum, optional) — Prepayment schedule type for this schedule
  - Allowed values: `FULL_UPFRONT`, `PER_COMMITMENT_PERIOD`, `SPLIT_ACROSS_BILLING_PERIODS`

### IntegratorsApiErrorDetails

Additional details about the error

### PeriodAmountsDto

- `cumulative` (string, required) — Cumulative amount
- `remaining` (string, required) — Remaining amount
- `trueUp` (string, required) — True-up amount

### EventTypeOverageDto

- `eventTypeId` (string, required) — Event type ID
- `cumulative` (MetricsDto, required) — Cumulative metrics for this event type across all periods
- `overages` (MetricsDto, required) — Overage metrics for this event type in this specific period
- `eventTypeName` (string, optional) — Event type name

### StepDto

- `id` (string, required) — Step ID
- `sequence` (double, required) — Dense step ordinal within the schedule (0..M-1)
- `effectiveCommitmentValue` (string, required) — Effective commitment value (original + amendments)
- `effectivePrepaidValue` (string, required) — Effective prepaid value (sum of linked PREPAID pricings)
- `prepaidEnabled` (boolean, required) — Whether prepaid is enabled for this step
- `commitmentUnitType` (enum, required) — Commitment unit type
  - Allowed values: `DOLLARS`, `UNITS`
- `pricePriority` (enum, required) — Price priority
  - Allowed values: `LOW`, `HIGH`
- `billingTermIds` (list of string, required) — Billing term IDs linked to this step
- `enteredAt` (string, optional) — When this step enters effect

## Examples

**Response**

```json
{
  "payload": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "contractId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "550e8400-e29b-41d4-a716-446655440000",
    "prepaidEnabled": false,
    "commitmentValue": "10000.00",
    "commitmentUnitType": "DOLLARS",
    "eventTypesIncluded": [
      "string",
      "string"
    ],
    "currentCumulative": {
      "amount": "150.50",
      "units": "1000"
    },
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z",
    "prepaidValue": "5000.00",
    "commitmentStartDate": "2024-01-01T00:00:00.000Z",
    "commitmentEndDate": "2024-12-31T00:00:00.000Z",
    "commitmentPeriodInterval": "MONTHLY",
    "commitmentCustomInterval": "3_MONTHS",
    "pricePriority": "LOW",
    "prepaymentScheduleType": "FULL_UPFRONT",
    "totals": {
      "overages": "250.50",
      "trueUps": "0.00"
    },
    "periods": [
      {
        "periodId": "550e8400-e29b-41d4-a716-446655440000",
        "periodDate": "2024-01-01T00:00:00.000Z",
        "amounts": {
          "cumulative": "5000.00",
          "remaining": "5000.00",
          "trueUp": "0.00"
        },
        "eventTypes": [
          {
            "eventTypeId": "550e8400-e29b-41d4-a716-446655440000",
            "cumulative": {
              "amount": "150.50",
              "units": "1000"
            },
            "overages": {
              "amount": "150.50",
              "units": "1000"
            },
            "eventTypeName": "API Calls"
          }
        ],
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z",
        "finalizedAt": null,
        "lastCalculatedAt": "2024-01-15T10:30:00.000Z"
      }
    ],
    "deletedAt": "string",
    "trueUpBehavior": "DEFAULT",
    "schedules": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "sequence": 0,
        "startDate": "2024-01-01T00:00:00.000Z",
        "endDate": "2024-12-31T00:00:00.000Z",
        "steps": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "sequence": 0,
            "effectiveCommitmentValue": "10000.00",
            "effectivePrepaidValue": "5000.00",
            "prepaidEnabled": false,
            "commitmentUnitType": "DOLLARS",
            "pricePriority": "LOW",
            "billingTermIds": [
              "string"
            ],
            "enteredAt": "2025-04-01T00:00:00.000Z"
          }
        ],
        "commitmentInterval": "DAILY",
        "prepaymentScheduleType": "FULL_UPFRONT"
      }
    ]
  },
  "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/commitments/commitmentId"

headers = {"Authorization": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://integrators.prod.api.tabsplatform.com/v3/commitments/commitmentId';
const options = {method: 'GET', headers: {Authorization: '<apiKey>'}};

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"
	"net/http"
	"io"
)

func main() {

	url := "https://integrators.prod.api.tabsplatform.com/v3/commitments/commitmentId"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<apiKey>")

	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/commitments/commitmentId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://integrators.prod.api.tabsplatform.com/v3/commitments/commitmentId")
  .header("Authorization", "<apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://integrators.prod.api.tabsplatform.com/v3/commitments/commitmentId', [
  'headers' => [
    'Authorization' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://integrators.prod.api.tabsplatform.com/v3/commitments/commitmentId");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://integrators.prod.api.tabsplatform.com/v3/commitments/commitmentId")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
```