Create revenue contract
POST/revenue/contracts
Creates a new revenue contract defining the term, total value, currency, and billing frequency for a customer engagement. Contracts must be created before billing schedules or subscriptions can be attached to them.
Request
Request body
Content type application/json (required).
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Human-readable contract title. Max length: 255 |
status | string | No | One of: |
start_date | string (date) | No | |
end_date | string (date), nullable | No | |
total_value | number (float) | No | Total contract value in the specified currency. |
currency | string | No | ISO 4217 currency code. Max length: 3 |
billing_frequency | string | No | One of: |
customer_id | integer | No | |
notes | string | No |
Example
{
"name": "Acme Corp Enterprise Agreement 2026",
"status": "draft",
"start_date": "2026-01-01",
"end_date": "2026-12-31",
"total_value": 48000.0,
"currency": "USD",
"billing_frequency": "monthly",
"customer_id": 88,
"notes": "Annual enterprise plan with quarterly review checkpoints."
}Responses
201 Contract created in draft status
Content type application/json, object · RevenueContractV1.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | No | Auto-incremented primary key. |
name | string | No | Descriptive name of the contract. |
status | string | No | Current lifecycle status of the contract. One of: |
start_date | string (date) | No | Contract commencement date. |
end_date | string (date), nullable | No | Contract expiry date. Null for open-ended contracts. |
total_value | number (float) | No | Total contract value in the specified currency. |
currency | string | No | ISO 4217 three-letter currency code (e.g. USD, GHS, EUR). Max length: 3 |
billing_frequency | string | No | How often billing events are generated for this contract. One of: |
customer_id | integer, nullable | No | ID of the associated customer record. |
notes | string, nullable | No | |
created_at | string (date-time) | No | |
updated_at | string (date-time) | No |
422 Validation failed — check date format, currency code, or customer_id
Example request
curl -X POST "https://{tenant}.faciotech.net/api/v1/revenue/contracts" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"name": "Acme Corp Enterprise Agreement 2026", "status": "draft", "start_date": "2026-01-01", "end_date": "2026-12-31", "total_value": 48000.0, "currency": "USD", "billing_frequency": "monthly", "customer_id": 88, "notes": "Annual enterprise plan with quarterly review checkpoints."}'