An organization’s active plan subscription. Subscriptions determine which Service Lines can be activated, gate usage limits, and generate invoices at the end of each billing period.
The Scrums.com API is planned and not yet publicly available. Endpoints and behaviour are subject to change before release.
A subscription (SUB-*) represents an organization’s active commitment to a Plan. Subscriptions are the commercial activation layer: when an organization subscribes to a plan, it unlocks the permitted product lines and usage limits across all its workspaces.Every Service Line is created against a subscription. This is how usage metering and billing trace back to the commercial contract. When a billing period closes, Invoices are generated from the subscription’s accrued usage.
An organization may hold multiple subscriptions if it has different commercial arrangements for different product lines or billing entities. Each subscription maps to one Plan and generates its own invoice series.
trialing -> active -> past_due -> cancelled | ^ +---> active ---------+ (if payment received)
A subscription transitions to past_due if the invoice is not settled by the due date. past_due subscriptions remain functional for a grace period before Service Lines are suspended.
A LIN-* always references a SUB-*. This ensures every unit of work has a clear commercial owner. Creating a Service Line requires a subscription_id referencing an active subscription on the same organization.
# Current period accrual vs forecastGET /v1/subscriptions/SUB-26-001122# Verify no invoices are past dueGET /v1/billing/invoices?subscription_id=SUB-26-001122&status=past_due
Validating a subscription before creating a Service Line
# Check the subscription is active and the product line is permittedGET /v1/subscriptions/SUB-26-001122# Verify plan allows the product lineGET /v1/plans/plan_enterprise_annual
Always reference the correct subscription_id on Service Lines. If an organization has multiple subscriptions, ensure each Service Line references the correct one. Misaligned subscriptions cause incorrect invoice attribution.
Monitor accrued_this_period against forecast. Significant divergence between accrual and forecast usually means a new Service Line was activated unexpectedly. Set up webhooks for service_line.activated events to catch this in real time.
Do not cancel subscriptions to pause work. Use PATCH /v1/service-lines/{lin_code}/transitions to pause individual Service Lines. Cancelling the subscription closes all Service Lines and invoices immediately.
