Zum Inhalt springen
Leadtime
Deutsch
EnglishDeutschNicht übersetzt
Esc
↑↓navigieren↵öffnen⌘Jvorschau

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:

  1. Specify the date range (fromDate to toDate) for when the subscription is active
  2. Set the frequency (1-12 months) to determine billing intervals:
    • 1 = monthly billing
    • 3 = quarterly billing
    • 6 = semi-annual billing
    • 12 = yearly billing
  3. 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)
  4. 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
or
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
201

Subscription billing created successfully

successbooleanrequired

Operation success flag

400

Invalid date range, frequency, or other validation error

401

Unauthorized - Invalid or missing authentication token

403

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

404

Project not found or access denied

Try it
Server
Authorization
Parameters
Bodyapplication/json
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"
}'
Response
{
  "success": true
}