v1

latestOpenAPI 3.1.02026-08-042453938.9 KB

Contracts

Amend a contract

Update an active contract's terms. Only ACTIVE contracts can be amended.

Provide only the fields you want to change — unspecified fields remain unchanged. Note that includedUnits and metadata are replaced entirely (not merged) when provided.

Cannot change: customerId, startDate, prepaidAmountUsdc, or status (use DELETE to cancel).

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

patch/v1/contracts/{id}

Path parameters

idstring required

Contract ID

Request body

namestring

Updated contract name

endDatestring date-time

Updated expiration date (ISO 8601). Set to extend or shorten the contract.

minimumUsdcstring

Updated minimum committed spend in USDC

maximumUsdcstring

Updated maximum spend cap in USDC

discountPctstring

Updated percentage discount (0-100)

includedUnitsobject

Updated free unit allocations. Replaces the entire includedUnits object (not merged).

metadataobject

Updated metadata. Replaces the entire metadata object (not merged).

Example request

{
  "name": "Acme Corp Enterprise Agreement (Amended)",
  "endDate": "2025-06-30T23:59:59.000Z",
  "minimumUsdc": "750.00",
  "maximumUsdc": "15000.00",
  "discountPct": "20",
  "includedUnits": {
    "api_call": 20000,
    "token": 2000000
  },
  "metadata": {
    "salesforceId": "OPP-12345",
    "tier": "enterprise",
    "amended": true
  }
}

Response

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