Create project subscription billing

What this endpoint does: Creates a new recurring subscription billing item for a project. The system automatically generates billing rows for each billing period based on your date range and frequency settings. These rows can later be included in invoices.

How it works:

Specify the date range (fromDate to toDate) for when the subscription is active
Set the frequency (1-12 months) to determine billing intervals:
- 1 = monthly billing
- 3 = quarterly billing
- 6 = semi-annual billing
- 12 = yearly billing
Choose the payment type:
- fixed: Fixed amount per period (e.g., $500/month)
- perUnit: Variable pricing (e.g., $50 per user per month)
- oneTime: One-time charge (requires quantity field)
The system automatically:
- Calculates sort order (display position)
- Generates billing rows for each period within the date range
- Creates date keys for invoice matching

Validation rules:

fromDate must be before or equal to toDate
Price must be positive
Frequency must be between 1 and 12 months
Quantity is required for oneTime payment type

Permissions required:

Projects.edit: Ability to edit project settings
Invoices.manage: Ability to manage invoice configurations

Example use cases:

Set up monthly support package subscription
Configure quarterly maintenance contract
Add yearly license renewal
Create variable pricing based on usage

POST/projects/{projectId}/subscription-billings

Authorization

AuthorizationOAuth2 access token · headerrequired

Scopes:api:write

AuthorizationBearer token (JWT) · headerrequired

Path parameters

projectIdstringrequired

Request body

requiredapplication/json

billingTimingstring

Invoice timing. **arrears** (default) = include a billing row in potential invoices only after the period ends. **advance** = include it from the first day of the billing period.

default: "arrears"

Allowed:arrearsadvance

frequencynumberrequired

Billing frequency in months. Determines how often billing rows are generated within the date range. Common values: 1 = monthly, 3 = quarterly, 6 = semi-annual, 12 = yearly. Must be between 1 and 12. Required.

min 1 · max 12

fromDatestringrequired

Start date when the subscription becomes active. Format: ISO 8601 date string (YYYY-MM-DD). The system will generate billing rows starting from the beginning of this month. Required.

manualTitlestringrequired

Human-readable title or description that appears on invoices and in project settings. Examples: "Monthly Support Package", "Quarterly Maintenance Contract", "Annual License Renewal". Required.

paymentstringrequired

Payment calculation method. "fixed" = fixed amount per billing period (e.g., $500/month). "perUnit" = variable pricing based on units (e.g., $50 per user per month). "oneTime" = one-time charge (requires quantity field). Required.

Allowed:fixedperUnitoneTime

pricenumberrequired

Price amount. For "fixed" payment type: amount per billing period. For "perUnit" payment type: price per unit. For "oneTime" payment type: total charge amount. Must be a positive number. Required.

quantitynumber

Quantity for variable pricing. Required when payment type is "oneTime" to calculate total charge (price × quantity). Optional for "fixed" and "perUnit" payment types.

toDatestringrequired

End date when the subscription expires. Format: ISO 8601 date string (YYYY-MM-DD). The system will generate billing rows up to the end of this month. Must be equal to or after fromDate. Required.

typestring

Type of subscription billing. Defaults to "manual" for API-created subscriptions. Use "product" only if linking to an existing product catalog item. Optional, defaults to manual.

default: "manual"

Allowed:manualproduct

Responses

201Subscription billing created successfully

successbooleanrequired

Operation success flag

400Invalid date range, frequency, or other validation error

401Unauthorized - Invalid or missing authentication token

403Insufficient permissions (requires Projects.edit and Invoices.manage)

404Project not found or access denied

Request

curl -X POST "https://leadtime.app/api/public/projects/string/subscription-billings" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "billingTiming": "arrears",
  "frequency": 1,
  "fromDate": "2024-01-01",
  "manualTitle": "Monthly Support Package",
  "payment": "fixed",
  "price": 5000,
  "quantity": 1,
  "toDate": "2024-12-31",
  "type": "manual"
}'

const response = await fetch("https://leadtime.app/api/public/projects/string/subscription-billings", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "billingTiming": "arrears",
  "frequency": 1,
  "fromDate": "2024-01-01",
  "manualTitle": "Monthly Support Package",
  "payment": "fixed",
  "price": 5000,
  "quantity": 1,
  "toDate": "2024-12-31",
  "type": "manual"
})
});

import requests

response = requests.post(
    "https://leadtime.app/api/public/projects/string/subscription-billings",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json"
    },
    json={
  "billingTiming": "arrears",
  "frequency": 1,
  "fromDate": "2024-01-01",
  "manualTitle": "Monthly Support Package",
  "payment": "fixed",
  "price": 5000,
  "quantity": 1,
  "toDate": "2024-12-31",
  "type": "manual"
},
)

Response

{
  "success": true
}