The Scrums.com API is planned and not yet publicly available. Endpoints and behaviour are subject to change before release.
Overview
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.
Core Concepts
One or more subscriptions per organization
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.
Subscription lifecycle
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.
Subscription and Service Line relationship
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.
Endpoints
GET /v1/subscriptions
List subscriptions for an organization.
Request
Response
POST /v1/subscriptions
Create a new subscription for an organization.
Request
Response
Returns the created subscription. Status is trialing if the plan has a trial period, otherwise active.
Notes
- Only org
owner or billing role can create subscriptions.
payment_method_id references a payment method stored in the billing system.
GET /v1/subscriptions/
Retrieve a subscription with current period accruals.
Response
PATCH /v1/subscriptions/
Update a subscription. Used primarily to change plans, update billing email, or schedule cancellation.
Request
Notes
- Plan changes (
plan_id) take effect at the start of the next billing period.
- Setting
cancel_at_period_end: true does not immediately cancel. The subscription continues until the period ends.
- Changing to a plan with fewer
allowed_product_lines may suspend active Service Lines that exceed the new plan’s limits.
DELETE /v1/subscriptions/
Cancel a subscription immediately. Outstanding usage is invoiced at the time of cancellation.
Notes
- Requires explicit confirmation. Pass
{ "confirm": true } in the request body.
- All Service Lines referencing this subscription are closed on cancellation.
- This action cannot be undone.
Common Workflows
Checking subscription health before quarter-end
Validating a subscription before creating a Service Line
Objects
Subscription
Best Practices
- 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.
