Create billing schedule

POST/revenue/billing-schedules

Creates a single billing schedule entry for a subscription. Use when manually adding a one-off billing event or when generating schedule entries for a newly created subscription that is not covered by automatic schedule generation.

Request

Request body

Content type application/json (required).

Field	Type	Required	Description
subscription_id	integer	Yes	ID of the subscription to associate this billing event with.
billing_date	string (date)	Yes	Target invoice date.
amount	number (float)	Yes	Amount to invoice.
currency	string	No	ISO 4217 currency code. Default: "USD" · Max length: 3
status	string	No	One of: "pending", "invoiced", "overdue", "cancelled" · Default: "pending"
notes	string	No

Example

{
  "subscription_id": 8,
  "billing_date": "2026-05-01",
  "amount": 4000.0,
  "currency": "USD",
  "status": "pending",
  "notes": "Month 5 of 12 — Enterprise plan."
}

Responses

201 Billing schedule entry created

Content type application/json, object · RevenueBillingScheduleV1.

Field	Type	Required	Description
id	integer	No	Auto-incremented primary key.
subscription_id	integer	No	ID of the subscription this billing event belongs to.
billing_date	string (date)	No	Date on which the billing event should be invoiced.
amount	number (float)	No	Amount to invoice for this billing event.
currency	string	No	ISO 4217 currency code. Max length: 3
status	string	No	Current processing status of the billing event. One of: "pending", "invoiced", "overdue", "cancelled"
notes	string, nullable	No
created_at	string (date-time)	No

422 Validation failed — check subscription_id, date format, or amount

Example request

curl -X POST "https://{tenant}.faciotech.net/api/v1/revenue/billing-schedules" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"subscription_id": 8, "billing_date": "2026-05-01", "amount": 4000.0, "currency": "USD", "status": "pending", "notes": "Month 5 of 12 — Enterprise plan."}'