v1

latestOpenAPI 3.1.02026-08-042453938.9 KB

Contracts

Cancel a contract

Cancel an active contract. Sets status to CANCELLED.

Cancellation is permanent — cancelled contracts cannot be reactivated. Any remaining prepaid balance is frozen. Price overrides from this contract stop applying to new charges immediately.

Already-cancelled contracts return a 400 error.

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

delete/v1/contracts/{id}

Path parameters

idstring required

Contract ID

Response

Contract cancelled 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"
    }
  ]
}