Subscription Lifecycle
A subscription tells Ticksupply to record a specific datastream for your account. Once active, it produces the data you can later pull through the Exports API. This guide explains the subscription state machine, what each transition does, and how a subscription’s history of active periods (“spans”) determines what is exportable.States
A subscription is always in exactly one of three states:| State | Meaning |
|---|---|
active | Data is being recorded. Exports for this subscription work within its recorded spans. |
paused | Recording is stopped. Data captured in earlier spans remains exportable; no new data is collected. |
deleted | Terminal. The subscription is no longer visible in GET /v1/subscriptions and its recorded spans are gone. |
Transitions
Each state change maps to a dedicated endpoint:| From → To | Endpoint | Effect on spans | Billing-gated |
|---|---|---|---|
(new) → active | POST /v1/subscriptions | Opens a new span starting now. | Yes |
active → paused | POST /v1/subscriptions/{id}/pause | Closes the current span (ended_at = now). | No |
paused → active | POST /v1/subscriptions/{id}/resume | Opens a new span starting now. | Yes |
any → deleted | DELETE /v1/subscriptions/{id} | All spans are removed. | No |
deleted → active | POST /v1/subscriptions with the same datastream_id | Reuses the same subscription ID, resets created_at, opens a fresh span. Prior spans are not restored. | Yes |
pause, resume, and delete are idempotent. Calling pause on an already-paused subscription (or resume on an already-active one) returns 204 No Content without changing anything. delete on an already-deleted subscription also succeeds without side effects.402 payment_required — see Billing interactions.
State diagram
Spans drive exportable time ranges
A span is a single[started_at, ended_at] window during which the subscription was recording. Exports are always clipped to the intersection of their requested time range with your subscription’s spans.
| State | Current spans |
|---|---|
active | One open span (ended_at is null) plus any closed spans from prior pause/resume cycles. |
paused | All spans are closed; the most recent ended_at marks when recording stopped. |
deleted | No spans exist. |
GET /v1/subscriptions/{id}/spans:
cURL
The
spans array on the POST /v1/subscriptions response is always []. Use GET /v1/subscriptions/{id}/spans right after creation to retrieve the initial open span.Billing interactions
Three lifecycle-related endpoints can return402 payment_required:
POST /v1/subscriptions— your plan has no room for another subscription, or the trial stream cap has been reached.POST /v1/subscriptions/{id}/resume— resuming would re-enable recording on a plan that currently disallows it (for example, a suspended or past-due plan).POST /v1/exports— billing rules deny the export (for example, the trial export cap has been reached).
pause and delete never return 402. See Error Handling for the full list of error codes.
Common questions
Can I export from a deleted subscription?
Can I export from a deleted subscription?
No. Deletion removes the subscription’s spans, and
POST /v1/exports returns 403 permission_denied with the message "Subscription has been deleted". If you want to stop collection but keep the data exportable, pause the subscription instead.Can I undo a deletion?
Can I undo a deletion?
The recorded history cannot be recovered. You can start a new recording for the same datastream by calling
POST /v1/subscriptions with the original datastream_id — the API reuses the subscription’s ID, resets created_at, and opens a fresh span. Data captured before deletion is not accessible from the restored subscription.What happens to data during the gap between pause and resume?
What happens to data during the gap between pause and resume?
Nothing is recorded. Pause closes the active span at the moment the call lands; resume opens a brand-new span. Exports that cross the gap skip that interval.
What if I try to create a duplicate subscription for the same datastream?
What if I try to create a duplicate subscription for the same datastream?
If an
active or paused subscription already exists for that datastream_id, the API returns 409 already_exists. Only deleted subscriptions can be recreated through this path — that is the “restore” flow described above.Does a paused subscription count against my plan limits?
Does a paused subscription count against my plan limits?
No. Only
active subscriptions count toward stream quota. Resuming a paused subscription is subject to billing and trial-limit checks at the moment of resumption.