---
title: "Preview commitment"
method: POST
path: "/commitments/preview"
tags: ["Commitments"]
---

# Preview commitment

`POST /commitments/preview`

## Request

- Base URL: `https://us.api.flexprice.io/v1`
- URL: `https://us.api.flexprice.io/v1/commitments/preview`
- Auth: API key in header `x-api-key`

Validates a commitment and returns its computed value without creating it.

## Request body

- CreateCommitmentRequest
  - `active_windows` TypesActiveWindow[]
    - `end` TypesBucket
      - `hour` integer
      - `minute` integer
    - `start` TypesBucket
      - `hour` integer
      - `minute` integer
  - `binding` boolean: default false
  - `collection_method` 'per_period' | 'billing_terms'
  - `committed_price` CommitmentPriceInput
    - `amount` string
    - `billing_model` 'FLAT_FEE' | 'PACKAGE' | 'TIERED'
    - `tier_mode` 'VOLUME' | 'SLAB'
    - `tiers` CreatePriceTier[]
      - `flat_amount` string: flat_amount is the flat amount for the given tier (optional) Applied on top of unit_amount*quantity. Useful for cases like "2.7$ + 5c"
      - `transform_quantity` PriceTransformQuantity
        - `divide_by` integer: Divide quantity by this number
        - `round` 'up' | 'down'
      - `unit_amount` string, required: unit_amount is the amount per unit for the given tier
      - `up_to` integer: up_to is the quantity up to which this tier applies. It is null for the last tier. IMPORTANT: Tier boundaries are INCLUSIVE. - If up_to is 1000, then quantity less than or equal to 1000 belongs to this tier - This behavior is consistent across both VOLUME and SLAB tier modes
    - `transform_quantity` PriceTransformQuantity
      - `divide_by` integer: Divide quantity by this number
      - `round` 'up' | 'down'
  - `end_date` string, date-time: EndDate is exclusive; omit it for an open-ended commitment, which bills every period until terminated.
  - `idempotency_key` string
  - `invoice_description` string
  - `invoice_label` string
  - `measurement` 'billing_period' | 'window', required
  - `metadata` TypesMetadata
  - `name` string, required
  - `overage_price` CommitmentPriceInput
    - `amount` string
    - `billing_model` 'FLAT_FEE' | 'PACKAGE' | 'TIERED'
    - `tier_mode` 'VOLUME' | 'SLAB'
    - `tiers` CreatePriceTier[]
      - `flat_amount` string: flat_amount is the flat amount for the given tier (optional) Applied on top of unit_amount*quantity. Useful for cases like "2.7$ + 5c"
      - `transform_quantity` PriceTransformQuantity
        - `divide_by` integer: Divide quantity by this number
        - `round` 'up' | 'down'
      - `unit_amount` string, required: unit_amount is the amount per unit for the given tier
      - `up_to` integer: up_to is the quantity up to which this tier applies. It is null for the last tier. IMPORTANT: Tier boundaries are INCLUSIVE. - If up_to is 1000, then quantity less than or equal to 1000 belongs to this tier - This behavior is consistent across both VOLUME and SLAB tier modes
    - `transform_quantity` PriceTransformQuantity
      - `divide_by` integer: Divide quantity by this number
      - `round` 'up' | 'down'
  - `priority` integer
  - `scope` CommitmentScopeInput, required
    - `entity_id` string: EntityID may be omitted on an inline subscription-scoped commitment; the new subscription's ID is used.
    - `entity_type` 'subscription' | 'group' | 'meter' | 'price', required
  - `start_date` string, date-time, required
  - `subscription_id` string: SubscriptionID is required on POST /commitments and set server-side on inline commitments.
  - `timezone` string
  - `type` 'amount' | 'quantity', required
  - `value` string

## Response `200`

OK

- CommitmentResponse
  - `active_windows` TypesActiveWindow[]
    - `end` TypesBucket
      - `hour` integer
      - `minute` integer
    - `start` TypesBucket
      - `hour` integer
      - `minute` integer
  - `binding` boolean
  - `collection_method` 'per_period' | 'billing_terms'
  - `commitment_status` 'active' | 'ended' | 'terminated'
  - `commitment_value` string
  - `committed_price_id` string
  - `created_at` string, date-time
  - `created_by` string
  - `currency` string
  - `customer_id` string
  - `end_date` string, date-time: EndDate is exclusive; nil for an open-ended commitment, which runs until terminated.
  - `environment_id` string
  - `id` string
  - `idempotency_key` string
  - `instalment_invoicing` string
  - `invoice_description` string
  - `invoice_label` string
  - `measurement` 'billing_period' | 'window'
  - `metadata` TypesMetadata
  - `name` string
  - `on_early_termination` 'forfeit' | 'credit_note' | 'bill_remaining'
  - `overage_price_id` string
  - `priority` integer
  - `scope_entity_id` string
  - `scope_entity_type` 'subscription' | 'group' | 'meter' | 'price'
  - `start_date` string, date-time
  - `status` 'published' | 'deleted' | 'archived'
  - `subscription_id` string
  - `tenant_id` string
  - `terminated_at` string, date-time
  - `termination_invoice_id` string
  - `timezone` string
  - `total_amount` string
  - `type` 'amount' | 'quantity'
  - `updated_at` string, date-time
  - `updated_by` string
  - `value` string

## Other responses

- `400`: Invalid request
- `500`: Server error

## Changes

- **2026-10-29** `e1348d61034c`: 1 info
  - the request property `end_date` became optional
- **2026-10-25** `3ec31fd2006a`: 2 info
  - the request property `scope/entity_id` became optional
  - the request property `subscription_id` became optional
- **2026-10-25** `3d4c411111a7`: 2 warning, 2 info
  - removed the request property `committed_rate`
  - removed the request property `overage_rate`
  - added the new optional request property `committed_price`
  - added the new optional request property `overage_price`
- **2026-10-25** `4746c65d9396`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/flexprice/apis/flexprice-api/changes/commitments/preview/post.md)

---

[API](https://skmtc.dev/flexprice/apis/flexprice-api.md) - [All operations](https://skmtc.dev/flexprice/apis/flexprice-api/llms.txt) - [OpenAPI document](https://skmtc.dev/flexprice/apis/flexprice-api/revisions/e1348d61034c?raw)