---
title: "List commitments"
method: GET
path: "/v3/commitments"
tags: ["Commitments"]
---

# List commitments

`GET /v3/commitments`

## Query parameters

- `page` number
- `limit` number
- `filter` string

## Response `200`

Get all commitments with optional customer and contract filtering

- object
  - `payload` object, required — Response payload, will be empty when success is false
    - `data` 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
      - `prepaidValue` string — Prepaid value if prepaid is enabled
      - `commitmentValue` string, required — Commitment value
      - `commitmentUnitType` 'DOLLARS' | 'UNITS', required — Commitment unit type
      - `commitmentStartDate` string — Commitment start date
      - `commitmentEndDate` string — Commitment end date (inclusive — the last day of the commitment)
      - `commitmentPeriodInterval` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'YEARLY' — Commitment period interval
      - `commitmentCustomInterval` string — Custom interval specification
      - `nextSequentialCommitmentId` string — ID of the next sequential commitment
      - `pricePriority` 'LOW' | 'HIGH' — Price priority for this commitment
      - `prepaymentScheduleType` 'FULL_UPFRONT' | 'PER_COMMITMENT_PERIOD' | 'SPLIT_ACROSS_BILLING_PERIODS' — Prepayment schedule type
      - `eventTypesIncluded` string[], required — List of event types included in this commitment
      - `currentCumulative` MetricsDto, required
        - `amount` string, required — Amount
        - `units` string, required — Units/quantity
      - `totals` TotalsDto
      - `periods` CommitmentPeriodDto[] — List of commitment periods with usage data
        - `periodId` string, required — Commitment period ID
        - `periodDate` string, required — Period start date
        - `amounts` PeriodAmountsDto, required
          - `cumulative` string, required — Cumulative amount
          - `remaining` string, required — Remaining amount
          - `trueUp` string, required — True-up amount
        - `eventTypes` EventTypeOverageDto[], required — Breakdown of usage by event type
          - `eventTypeId` string, required — Event type ID
          - `eventTypeName` string — Event type name
          - `cumulative` MetricsDto, required
            - `amount` string, required — Amount
            - `units` string, required — Units/quantity
          - `overages` MetricsDto, required
            - `amount` string, required — Amount
            - `units` string, required — Units/quantity
        - `finalizedAt` string, nullable — Timestamp when the period was finalized; null if not yet finalized
        - `lastCalculatedAt` string — Last time the period was calculated
        - `createdAt` string, required — Created at timestamp
        - `updatedAt` string, required — Updated at timestamp
      - `createdAt` string, required — Created at timestamp
      - `updatedAt` string, required — Updated at timestamp
      - `deletedAt` string — Soft delete timestamp (null if not deleted)
      - `trueUpBehavior` 'DEFAULT' | 'NEVER' — True-up behavior for the commitment (commitments-v2)
      - `schedules` ScheduleDto[] — Nested schedule/step structure (commitments-v2). Present only when the commitment has been migrated and the manufacturer is on the commitments-v2 flag. The top-level fields above are sourced from schedule 0 / step 0 for back-compat.
        - `id` string, required — Schedule ID
        - `sequence` number, 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)
        - `commitmentInterval` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'YEARLY' — Commitment period interval for this schedule
        - `prepaymentScheduleType` 'FULL_UPFRONT' | 'PER_COMMITMENT_PERIOD' | 'SPLIT_ACROSS_BILLING_PERIODS' — Prepayment schedule type for this schedule
        - `steps` StepDto[], required — Steps within this schedule (dense, ordered)
          - `id` string, required — Step ID
          - `sequence` number, 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` 'DOLLARS' | 'UNITS', required — Commitment unit type
          - `pricePriority` 'LOW' | 'HIGH', required — Price priority
          - `billingTermIds` string[], required — Billing term IDs linked to this step
          - `enteredAt` string — When this step enters effect
    - `limit` number
    - `totalItems` number
    - `currentPage` number
  - `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

- `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/revisions/7e8885517814/schema)