Create subscription

POST/revenue/subscriptions

Creates a new subscription record for a customer, linking it to a contract and price book. Subscription creation does not automatically generate billing schedules — use the /billing-schedules endpoint to create schedule entries as needed.

Request

Request body

Content type application/json (required).

Field	Type	Required	Description
name	string	Yes	Max length: 255
status	string	No	One of: "trial", "active", "paused", "cancelled", "expired" · Default: "active"
contract_id	integer	No
price_book_id	integer	No
customer_id	integer	No
start_date	string (date)	No
end_date	string (date), nullable	No
monthly_value	number (float)	No
currency	string	No	Default: "USD" · Max length: 3
seats	integer	No

Example

{
  "name": "Acme Corp — Enterprise Plan",
  "status": "active",
  "contract_id": 12,
  "price_book_id": 3,
  "customer_id": 88,
  "start_date": "2026-01-01",
  "end_date": "2026-12-31",
  "monthly_value": 4000.0,
  "currency": "USD",
  "seats": 50
}

Responses

201 Subscription created

Content type application/json, object · RevenueSubscriptionV1.

Field	Type	Required	Description
id	integer	No
name	string	No	Descriptive name for the subscription.
status	string	No	One of: "trial", "active", "paused", "cancelled", "expired"
contract_id	integer, nullable	No	ID of the governing revenue contract.
price_book_id	integer, nullable	No	ID of the price book used to price this subscription.
customer_id	integer, nullable	No
start_date	string (date)	No
end_date	string (date), nullable	No
monthly_value	number (float)	No	Monthly recurring revenue value of this subscription.
currency	string	No	Max length: 3
seats	integer, nullable	No	Number of licensed seats (if seat-based pricing).
next_billing_date	string (date), nullable	No
created_at	string (date-time)	No

422 Validation failed — check contract_id, price_book_id, or date range

Example request

curl -X POST "https://{tenant}.faciotech.net/api/v1/revenue/subscriptions" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp — Enterprise Plan", "status": "active", "contract_id": 12, "price_book_id": 3, "customer_id": 88, "start_date": "2026-01-01", "end_date": "2026-12-31", "monthly_value": 4000.0, "currency": "USD", "seats": 50}'