v1

latestOpenAPI 3.1.02026-08-042453938.9 KB

Contracts

Create a contract

Create a per-customer commercial agreement with custom pricing, prepaid commits, and spend caps.

Contracts override default pricing plans for a specific customer. Use them for:

Enterprise deals with negotiated rates (via price overrides)
Prepaid commits where the customer pays upfront and draws down a balance
Spend caps to enforce maximum billing per period
Minimum commits to guarantee a revenue floor
Volume discounts applied as a percentage across all usage
Free-tier allocations with included units per usage type

The customerId must reference a customer created via POST /customers. If prepaidAmountUsdc is provided, the contract is initialized with that amount as prepaidBalanceUsdc.

Requires a secret key (sk_*) with the ADMIN role.

post/v1/contracts

Request body

customerIdstring required

ID of the customer this contract applies to. Must be a valid customer ID returned from POST /customers.

namestring required

Human-readable name for the contract (e.g., "Acme Corp Enterprise Q1 2024")

startDatestring date-time required

When the contract takes effect (ISO 8601). Can be in the future for scheduled activations.

endDatestring date-time

When the contract expires (ISO 8601). Omit for a perpetual contract with no end date.

minimumUsdcstring

Minimum committed spend in USDC. The customer is billed for at least this amount regardless of actual usage. Use for minimum-commit deals.

maximumUsdcstring

Maximum spend cap in USDC. Charges that would exceed this cap are blocked. Use for budget-capped agreements.

discountPctstring

Percentage discount applied to all charges (0-100). For example, "15" means 15% off all usage charges under this contract.

prepaidAmountUsdcstring

Prepaid commit amount in USDC. This amount is pre-loaded as a credit balance. Charges draw down from this balance first before falling back to normal billing.

prepaidRolloverboolean

Whether unused prepaid balance rolls over to the next billing period. Defaults to false (unused balance expires).

includedUnitsobject

Free unit allocations per usage type. Keys are unit types (must match pricing plan unitType), values are the number of free units per billing period. Usage within these limits is not charged.

metadataobject

Arbitrary key-value metadata. Useful for storing external references (CRM deal IDs, internal tags, etc.).

Example request

{
  "customerId": "cus_abc123def456",
  "name": "Acme Corp Enterprise Agreement",
  "startDate": "2024-01-01T00:00:00.000Z",
  "endDate": "2024-12-31T23:59:59.000Z",
  "minimumUsdc": "500.00",
  "maximumUsdc": "10000.00",
  "discountPct": "15",
  "prepaidAmountUsdc": "1000.00",
  "includedUnits": {
    "api_call": 10000,
    "token": 1000000
  },
  "metadata": {
    "salesforceId": "OPP-12345",
    "tier": "enterprise"
  }
}

Response

Contract created successfully

idstring required

Unique identifier for the contract

businessIdstring required

Business that owns this contract

customerIdstring required

Customer this contract applies to (must be created via POST /customers first)

namestring required

Human-readable name for the contract

status'ACTIVE' | 'PAUSED' | 'EXPIRED' | 'CANCELLED' required

Current contract status. Only ACTIVE contracts affect billing. Transitions: ACTIVE → PAUSED, EXPIRED, or CANCELLED.

startDatestring date-time required

When the contract takes effect (ISO 8601)

endDatestring date-time nullable

When the contract expires (ISO 8601). Null means the contract is perpetual.

minimumUsdcstring nullable

Minimum committed spend in USDC for the contract period. If the customer spends less, they are still billed for the minimum.

maximumUsdcstring nullable

Maximum spend cap in USDC for the contract period. Charges that would exceed this cap are blocked.

discountPctstring nullable

Percentage discount applied to all charges under this contract (0-100, up to 2 decimal places)

prepaidAmountUsdcstring nullable

Total prepaid commit amount in USDC. This is the initial balance loaded into the contract.

prepaidBalanceUsdcstring nullable

Remaining prepaid balance in USDC. Decreases as charges are applied. When depleted, charges fall back to normal billing.

prepaidRolloverboolean required

Whether unused prepaid balance rolls over to the next billing period

includedUnitsobject nullable

Free unit allocations per usage type per billing period. Usage within these limits is not charged. Keys are unit types, values are quantities.

metadataobject nullable

Arbitrary key-value metadata for your own tracking (e.g., Salesforce deal ID, internal notes)

createdAtstring date-time required

When the contract was created

updatedAtstring date-time required

When the contract was last updated

Example response

{
  "id": "ctr_abc123def456",
  "businessId": "biz_789xyz",
  "customerId": "cus_abc123def456",
  "name": "Acme Corp Enterprise Agreement",
  "status": "ACTIVE",
  "startDate": "2024-01-01T00:00:00.000Z",
  "endDate": "2024-12-31T23:59:59.000Z",
  "minimumUsdc": "500.000000",
  "maximumUsdc": "10000.000000",
  "discountPct": "15.00",
  "prepaidAmountUsdc": "1000.000000",
  "prepaidBalanceUsdc": "750.000000",
  "includedUnits": {
    "api_call": 10000,
    "token": 1000000
  },
  "metadata": {
    "salesforceId": "OPP-12345",
    "tier": "enterprise"
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "priceOverrides": [
    {
      "id": "cpo_abc123def456",
      "unitType": "api_call",
      "unitPriceUsd": "0.000800"
    }
  ]
}