---
title: "Create a contract"
method: POST
path: "/v1/contracts"
tags: ["Contracts"]
---

# Create a contract

`POST /v1/contracts`

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.**

## Request body

- object — Create a per-customer commercial agreement. Use contracts to offer enterprise customers custom pricing, prepaid commits, spend caps, and volume discounts. The customer must already exist (created via `POST /customers`).
  - `customerId` string, required — ID of the customer this contract applies to. Must be a valid customer ID returned from `POST /customers`.
  - `name` string, required — Human-readable name for the contract (e.g., "Acme Corp Enterprise Q1 2024")
  - `startDate` string, date-time, required — When the contract takes effect (ISO 8601). Can be in the future for scheduled activations.
  - `endDate` string, date-time — When the contract expires (ISO 8601). Omit for a perpetual contract with no end date.
  - `minimumUsdc` string — Minimum committed spend in USDC. The customer is billed for at least this amount regardless of actual usage. Use for minimum-commit deals.
  - `maximumUsdc` string — Maximum spend cap in USDC. Charges that would exceed this cap are blocked. Use for budget-capped agreements.
  - `discountPct` string — Percentage discount applied to all charges (0-100). For example, "15" means 15% off all usage charges under this contract.
  - `prepaidAmountUsdc` string — 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.
  - `prepaidRollover` boolean — Whether unused prepaid balance rolls over to the next billing period. Defaults to false (unused balance expires).
  - `includedUnits` object — 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.
  - `metadata` object — Arbitrary key-value metadata. Useful for storing external references (CRM deal IDs, internal tags, etc.).

## Response `201`

Contract created successfully

- object — Contract created successfully
  - `id` string, required — Unique identifier for the contract
  - `businessId` string, required — Business that owns this contract
  - `customerId` string, required — Customer this contract applies to (must be created via POST /customers first)
  - `name` string, 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.
  - `startDate` string, date-time, required — When the contract takes effect (ISO 8601)
  - `endDate` string, date-time, nullable — When the contract expires (ISO 8601). Null means the contract is perpetual.
  - `minimumUsdc` string, nullable — Minimum committed spend in USDC for the contract period. If the customer spends less, they are still billed for the minimum.
  - `maximumUsdc` string, nullable — Maximum spend cap in USDC for the contract period. Charges that would exceed this cap are blocked.
  - `discountPct` string, nullable — Percentage discount applied to all charges under this contract (0-100, up to 2 decimal places)
  - `prepaidAmountUsdc` string, nullable — Total prepaid commit amount in USDC. This is the initial balance loaded into the contract.
  - `prepaidBalanceUsdc` string, nullable — Remaining prepaid balance in USDC. Decreases as charges are applied. When depleted, charges fall back to normal billing.
  - `prepaidRollover` boolean, required — Whether unused prepaid balance rolls over to the next billing period
  - `includedUnits` object, nullable — Free unit allocations per usage type per billing period. Usage within these limits is not charged. Keys are unit types, values are quantities.
  - `metadata` object, nullable — Arbitrary key-value metadata for your own tracking (e.g., Salesforce deal ID, internal notes)
  - `createdAt` string, date-time, required — When the contract was created
  - `updatedAt` string, date-time, required — When the contract was last updated
  - `priceOverrides` object[], required — Custom per-unit-type pricing that overrides default pricing plans for this customer
    - `id` string, required — Unique identifier for the price override
    - `unitType` string, required — The usage type this override applies to (must match a pricing plan `unitType`)
    - `unitPriceUsd` string, required — Custom price per unit in USD (string for decimal precision, up to 6 decimal places)

## Other responses

- `400` — Validation error (missing required fields, invalid format)
- `401` — Unauthorized — missing or invalid API key
- `403` — Forbidden — API key does not have ADMIN role
- `404` — Customer not found — the `customerId` does not exist or does not belong to your business

---

[API](https://skmtc.net/usedrip/apis/drip-api.md) · [All operations](https://skmtc.net/usedrip/apis/drip-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/usedrip/drip-api/revisions/2cb1567969ca/schema)