Read your monthly minimum commitment and the current month's progress

GET

/commitment

const url = 'https://example.com/v2/commitment';
const options = {method: 'GET', headers: {'X-CowriePay-Key': '<X-CowriePay-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://example.com/v2/commitment \
  --header 'X-CowriePay-Key: <X-CowriePay-Key>'

Returns the negotiated monthly minimum commitment attached to your workspace, if any, with the current calendar month’s progress and the last twelve monthly adjustments.

Read-only: a commitment exists only on a signed contract and is set up by CowriePay. When there is nothing to show, commitment and current_period are null, adjustments is empty and outstanding_total_usdt is "0.000000".

How a month settles: on each closed calendar month, the fees actually billed to your workspace (mainnet stablecoins only) are compared with the floor, prorated on your first and last month. When they fall short, a catch-up adjustment for the difference is emitted, notified by the COMMITMENT_ADJUSTMENT_EMITTED webhook, and either debited from your available balance in the settlement asset (never below zero, the remainder stays outstanding) or settled with CowriePay operations, depending on the contract. projected_fees_usdt is a straight-line projection and is indicative only.

Which commitment you get back: the active one if you have one; otherwise a suspended one, which is paused rather than over; otherwise an ended one that still carries an unsettled adjustment. The last month of a commitment is billed after it ends, so an ended commitment stays readable here until everything owed on it is settled, and then stops being returned.

current_period is null whenever the commitment does not cover the current calendar month, which is the case for an ended commitment and for one that has not started yet. Read outstanding_total_usdt rather than summing adjustments: it covers every commitment on the workspace and is not truncated to the twelve rows returned here.

Authorizations

ApiKeyAuth

Responses

200

The commitment, the current month, and recent adjustments.

application/json

object

commitment

required

object

string format: uuid

monthly_floor_usdt

The agreed monthly floor, in USDT.

string

settlement_asset

The stablecoin an on-platform debit is taken in.

string

Allowed values: USDT_TRON USDT_BSC USDT_ETH USDC_ETH EURC_ETH

starts_at

string format: date-time

ends_at

string | null format: date-time

status

string

Allowed values: ACTIVE SUSPENDED ENDED

auto_debit

True when a shortfall is debited from the available balance automatically.

boolean

contract_reference

string

current_period

required

object

period_start

string format: date-time

period_end

Exclusive.

string format: date-time

days_covered

integer

days_in_month

integer

prorated_floor_usdt

string

billed_fees_usdt

Fees billed so far this month that count toward the floor.

string

remaining_to_floor_usdt

Floor minus billed fees, floored at zero.

string

projected_fees_usdt

Straight-line projection to month end. Indicative.

string

indicative

boolean

adjustments

required

The last twelve monthly adjustments, newest first.

Array<object>

object

string format: uuid

period_start

string format: date-time

period_end

string format: date-time

prorated_floor_usdt

string

billed_fees_usdt

string

delta_usdt

The shortfall billed as a catch-up; “0.000000” when the floor was met.

string

recovery_mode

string

Allowed values: AUTO_DEBIT MANUAL

debited_usdt

string

outstanding_usdt

string

status

string

Allowed values: NOT_DUE OPEN SETTLED

settled_at

string | null format: date-time

outstanding_total_usdt

required

Everything still owed on this workspace, across every commitment it holds, summed server-side. Use this rather than summing adjustments, which is capped at twelve rows and would under-report an older unsettled adjustment. “0.000000” when nothing is owed.

string

Example

{
  "commitment": {
    "id": "8b1b6d2e-3a4f-4c1d-9e0a-2f6c7d8e9f01",
    "monthly_floor_usdt": "500.000000",
    "settlement_asset": "USDT_TRON",
    "starts_at": "2026-09-01T00:00:00.000Z",
    "ends_at": null,
    "status": "ACTIVE",
    "auto_debit": false,
    "contract_reference": "CTR-2026-014"
  },
  "current_period": {
    "period_start": "2026-10-01T00:00:00.000Z",
    "period_end": "2026-11-01T00:00:00.000Z",
    "days_covered": 31,
    "days_in_month": 31,
    "prorated_floor_usdt": "500.000000",
    "billed_fees_usdt": "212.400000",
    "remaining_to_floor_usdt": "287.600000",
    "projected_fees_usdt": "470.100000",
    "indicative": true
  },
  "adjustments": [
    {
      "id": "c0a1f2e3-5d6b-4a7c-8e9f-0a1b2c3d4e5f",
      "period_start": "2026-09-01T00:00:00.000Z",
      "period_end": "2026-10-01T00:00:00.000Z",
      "prorated_floor_usdt": "500.000000",
      "billed_fees_usdt": "120.500000",
      "delta_usdt": "379.500000",
      "recovery_mode": "MANUAL",
      "debited_usdt": "0.000000",
      "outstanding_usdt": "379.500000",
      "status": "OPEN",
      "settled_at": null
    }
  ],
  "outstanding_total_usdt": "379.500000"
}

401

Invalid or revoked API key / HMAC signature mismatch

application/json

object

error

required

Human-readable message, for display/logging. Do NOT branch on this text.

string

code

required

Stable, machine-readable error code, branch on this, not the message. Common values: VALIDATION_ERROR, INVALID_JSON, PAYLOAD_TOO_LARGE, MISSING_AUTH_HEADERS, INVALID_SIGNATURE, TIMESTAMP_EXPIRED, REPLAY_DETECTED, INVALID_API_KEY, IP_NOT_ALLOWED, API_KEY_EXPIRED, WORKSPACE_INACTIVE, INSUFFICIENT_SCOPE, NOT_FOUND, CONFLICT, UNPROCESSABLE, INSUFFICIENT_BALANCE, INVALID_DESTINATION_ADDRESS, DESTINATION_IS_INTERNAL, CHAIN_NOT_ENABLED, FAUCET_ONLY_SANDBOX, FAUCET_ADDRESS_NOT_FOUND, FAUCET_INVALID_ASSET, FAUCET_AMOUNT_OVER_CAP, FAUCET_RATE_LIMITED, FAUCET_TOO_MANY_ITEMS, FAUCET_DUPLICATE_ASSET, FAUCET_NATIVE_REQUIRES_DEPOSIT, FAUCET_NATIVE_BUDGET_EXCEEDED, FAUCET_DISPENSER_EXHAUSTED, WITHDRAWAL_NOT_CANCELLABLE, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_MISMATCH, IDEMPOTENCY_KEY_INVALID, FEATURE_NOT_AVAILABLE, RATE_LIMITED, DATABASE_ERROR, INTERNAL_ERROR, UNAUTHORIZED, FORBIDDEN, UNSUPPORTED_MEDIA_TYPE, WITHDRAWALS_FROZEN, WORKSPACE_NOT_FOUND, SYSTEM_WORKSPACE_PROTECTED, FAUCET_INVALID_AMOUNT, FAUCET_NO_ASSETS, FAUCET_NOT_SANDBOX. Most failures do NOT carry a business code. 326 throw sites raise a generic one (VALIDATION_ERROR, NOT_FOUND, UNPROCESSABLE, UNAUTHORIZED, CONFLICT, FORBIDDEN) against 46 named public codes, so a generic code is the common case and a named one is the exception. Branch on code; treat error as human text that may be reworded. The full catalogue, with causes and next steps, is the Error codes guide.

string

Example

{
  "error": "Insufficient balance. Available: 10.000000, Requested: 50.000000",
  "code": "INSUFFICIENT_BALANCE"
}

403

The key lacks the fees:read scope

application/json

object

error

required

Human-readable message, for display/logging. Do NOT branch on this text.

string

code

required

string

Example

{
  "error": "Insufficient balance. Available: 10.000000, Requested: 50.000000",
  "code": "INSUFFICIENT_BALANCE"
}