---
title: "Create commitments"
method: POST
path: "/v3/commitments"
tags: ["Commitments"]
---

# Create commitments

`POST /v3/commitments`

## Request body

- CreateUsageCommitmentsV3RequestDto
  - `contractId` string, required — The contract ID
  - `commitments` CreateUsageCommitmentV3Dto[], required — Array of commitments to create
    - `commitmentValue` number, required — The commitment amount value
    - `commitmentUnitType` 'DOLLARS' | 'UNITS', required — Unit type: DOLLARS or UNITS
    - `prepaidEnabled` boolean, required — Whether prepaid is enabled
    - `prepaidValue` number — Prepaid amount value (required if prepaidEnabled is true)
    - `prepaymentInvoiceLineName` string — Name of prepayment invoice line item
    - `prepaymentIntegrationItem` string — Integration item ID for prepayment
    - `revenueRecognitionPattern` string — Revenue recognition pattern: straight-line or recognize-as-consumed
    - `trueUpName` string — Name of true-up invoice line item (for non-prepaid)
    - `trueUpIntegrationItem` string — Integration item ID for true-up invoice line (non-prepaid)
    - `billingTermIds` string[], required — Billing term IDs to link to this commitment
    - `commitmentStartDate` string — Commitment start date (YYYY-MM-DD)
    - `commitmentEndDate` string — Commitment end date, inclusive (YYYY-MM-DD)
    - `isFullDuration` boolean — Whether commitment lasts the full duration
    - `commitmentInterval` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'YEARLY' — Commitment period interval
    - `isSequential` boolean — Whether this is a sequential commitment
    - `previousCommitmentId` string — ID of the previous commitment if sequential
    - `prePaidWholeCommitment` boolean — Whether the whole commitment is prepaid upfront (pay-in-full). False means split-payment. Deprecated: use prepaymentScheduleType instead.
    - `prepaymentScheduleType` 'FULL_UPFRONT' | 'PER_COMMITMENT_PERIOD' | 'SPLIT_ACROSS_BILLING_PERIODS' — Prepayment schedule type. Takes precedence over prePaidWholeCommitment. Defaults to FULL_UPFRONT when omitted and prepaidEnabled is true.
    - `pricePriority` 'LOW' | 'HIGH' — Price priority: LOW or HIGH
    - `overageConfigs` CreateUsageCommitmentOverageConfigV3Dto[] — Overage pricing configuration per billing term
      - `billingTermId` string, required — Billing term ID this overage config applies to
      - `overagePrice` number, required — Price per unit for overage
      - `overageInvoiceLineName` string — Display name for overage invoice line item
      - `overageIntegrationItemId` string — Integration item ID for overage invoice line item
      - `overagePricings` CreateUsageCommitmentOveragePricingItemV3Dto[] — Detailed pricing tiers for overage
        - `name` string, required — Pricing name
        - `mantissa` string — Mantissa for the price
        - `exponent` string — Exponent for the price
        - `currency` 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLE' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VED' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMW' | 'ZWG' | 'ZWL' — ISO 4217 currency code
        - `tier` number — Tier number
        - `conditionValue` number — Condition value for tier
        - `isOverage` boolean — Whether this pricing is for overage
    - `schedules` CreateUsageCommitmentScheduleV3Dto[] — Nested schedule/step structure (commitments-v2). Additive to the flat fields above (which describe the parent commitment / schedule 0 / step 0). When omitted, the server synthesizes a single-schedule × single-step tree from the flat fields. Honoured only when the manufacturer is on the commitments-v2 flag.
      - `sequence` number, required — Dense schedule ordinal within the commitment (0..N-1)
      - `startDate` string, required — Schedule start date (YYYY-MM-DD)
      - `endDate` string, required — Schedule end date, inclusive (YYYY-MM-DD)
      - `commitmentInterval` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'YEARLY' — Commitment period interval
      - `prepaymentScheduleType` 'FULL_UPFRONT' | 'PER_COMMITMENT_PERIOD' | 'SPLIT_ACROSS_BILLING_PERIODS' — Prepayment schedule type for this schedule
      - `steps` CreateUsageCommitmentStepV3Dto[], required — Steps within this schedule (dense, ordered)
        - `sequence` number, required — Dense step ordinal within the schedule (0..M-1)
        - `commitmentValue` number, required — The commitment amount value for this step
        - `commitmentUnitType` 'DOLLARS' | 'UNITS', required — Unit type: DOLLARS or UNITS
        - `prepaidEnabled` boolean, required — Whether prepaid is enabled for this step
        - `prepaidValue` number — Prepaid amount value (required if prepaidEnabled is true)
        - `pricePriority` 'LOW' | 'HIGH' — Price priority: LOW or HIGH
        - `billingTermIds` string[], required — Billing term IDs to link to this step
        - `billingTermCommitmentType` 'TRUE_UP' | 'OVERAGE' | 'PREPAID' — Optional commitment-type tag applied to this step's billing terms (TRUE_UP | OVERAGE | PREPAID)
        - `enteredAt` string — When this step enters effect (YYYY-MM-DD). For multi-step (step-up) schedules each step enters at a different time; defaults to the schedule start date when omitted.

## Response `201`

Usage commitments created successfully

- object
  - `payload` object, required — Response payload, will be empty when success is false
    - `success` boolean
    - `commitmentIds` string[]
  - `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

- `400` — Validation error or BT lockdown
- `404` — Contract not found

---

[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)