Subscriptions
A subscription is the contract between you and one customer: who is billed, in which currency, for what, and from when. It is where the catalog stops being a catalog and starts producing invoices.
A subscription has two layers, and almost everything on this page follows from keeping them apart:
- The envelope is the subscription object itself (
GET /v1/subscriptions/{id}): itsid,customer_id,currency,status, name and the billing calendar the deal produced.PATCH /v1/subscriptions/{id}edits only the descriptive fields of the envelope (name,description,translations,custom_fields,on_early_stop). It never changes what is billed. - The deal is what was agreed: which products, at which quantities and prices, over which stretches of time. It lives in revisions. A revision is an ordered list of phases, and each phase holds lines, one per product billed in that window.
You never edit a live deal in place. You open a draft revision, change it, and publish it. The previous revision is kept as history.
Status
status has four values: DRAFT, ACTIVE, PAUSED and
CANCELLED.
| Status | Meaning | How it gets there |
|---|---|---|
DRAFT | Created, nothing agreed is in force, nothing bills. | POST /v1/subscriptions, or a quote that adds a new subscription |
ACTIVE | Revision 1 is published; the phases bill as they come due. | POST /v1/subscriptions/{id}/activate, a signed quote, or a resume |
PAUSED | Billing and the phase clocks are frozen. | POST /v1/subscriptions/{id}/pause |
CANCELLED | Ended. Terminal. | POST /v1/subscriptions/{id}/cancel, a last phase with then: "stop", or the end of the dunning ladder |
actions on the subscription (GET /v1/subscriptions/{id}?include=actions) says
which lifecycle calls it accepts now: activate, pause, resume, cancel and
edit_draft, each true or false. Read it instead of hard-coding the table.
It replaces allowed_transitions, which is deprecated and removed on 2026-11-30.
There is no trialing, past-due or expired status. A trial is a phase whose
lines are priced free. Dunning shows in billing_state on
GET /v1/subscriptions/{id} (dunning_stage, overdue_invoices, held_since),
not in the status. A deal that does not renew ends through its last phase
saying then: "stop", which cancels it.
cancellation_reason says why a CANCELLED subscription ended:
cancellation_reason | Meaning |
|---|---|
USER_REQUEST | An operator or the customer cancelled it. |
DUNNING_TERMINAL | The dunning ladder reached its last step. |
AGREEMENT_TERM_ENDED | Its last phase ended with then: "stop": the deal ran its course. |
Read the reason before counting churn: AGREEMENT_TERM_ENDED is a fixed-term
deal that ended as planned, not a customer walking away.
Two spellings of the same status
The subscription object spells the status in capitals (ACTIVE). The revision
endpoints (GET /v1/subscriptions/{id}/revisions/live and the write operations
that return the deal) spell it in lower case (active). Both describe the same
state.
The deal: revisions, phases and lines
Revisions
A subscription has exactly one live revision once it has started, any number
of superseded ones, and at most one draft. Revisions are numbered from 1.
GET /v1/subscriptions/{id}?include=revisions names the live revision and the
open draft (revisions.live, revisions.draft, each with id, number and
status). revisions.draft is absent when no draft is open. It replaces
has_draft, which is deprecated and removed on 2026-11-30.
| Read | Endpoint |
|---|---|
| The deal as it stands, every value resolved | GET /v1/subscriptions/{id}/revisions/live |
| The phase windows as concrete instants | GET /v1/subscriptions/{id}/revisions/live?include=phases: each phase's window has start, end and state |
| The open draft | GET /v1/subscriptions/{id}/revisions/draft |
| Every revision, without phases | GET /v1/subscriptions/{id}/revisions |
| One revision by number | GET /v1/subscriptions/{id}/revisions/{number} |
GET …/revisions/live answers 404 while the subscription is still DRAFT:
there is no live deal yet.
GET /v1/subscriptions/{id}/revisions/live/timeline is deprecated and removed on
2026-11-30. Read the windows from the live revision instead, as in the table.
What the subscription says about its deal
The subscription object answers a few facts about its live revision under
live (GET /v1/subscriptions/{id}?include=live):
Response 200 (abridged)
This is the deal of the worked example below, read on 20 February 2027 after its change to 25 seats. It assumes a monthly plan with a list price of €49.00 per seat and periods aligned to the start of the first paid phase (15 November).
The top-level mrr, arr, current_period, next_cut_at,
scheduled_start, auto_renew and effective_track are deprecated and removed
on 2026-11-30. Read them under live instead. arr has no new field: it is 12 ×
live.mrr. scheduled_start is live.starts_at while that is still ahead.
Other blocks come only when you name them in include: revisions, actions,
scheduled_cancellation, billing_state and localized.
Phases
A phase is a window of time with its own lines. It is described by rules, not by stored dates:
| Field | Values | Meaning |
|---|---|---|
starts.kind | fixed (with starts.at), after_previous | Opens on a date, or when the previous phase closes. Phase 0 must be fixed. |
ends.kind | date (with ends.at), duration (with ends.duration), event (with ends.event), never | How the window closes. A duration is {"count": 12, "unit": "month"}; units are day, week, month, year. |
then | next, open, stop | What follows. next exactly when a later phase exists; open or stop only on the last phase. |
exit | gate, not_before, notice_duration, fee | The phase's exit rules. See Commitments and exit rules. |
reason | text | Why the phase exists. |
lines | array | One entry per product billed in the window. |
then: "open" on the last phase means the deal runs on past it (the
subscription's read-only live.auto_renew is then true). then: "stop" ends the
subscription when the last phase closes, with cancellation_reason
AGREEMENT_TERM_ENDED.
Phases must tile time: no gaps and no overlaps. A fixed start after the first
phase must meet the previous phase's end exactly.
Lines and the value ladder
A line names a product_id, its origin ({"kind": "plan" | "product", "id": …, "version": …}, the plan or product version it was taken from) and optionally a
price_key. Everything else about the line is a set of values, keyed by
attribute:
| Attribute | Value shape |
|---|---|
quantity | {"kind": "stated", "quantity": "10"} |
price | {"kind": "stated", "price": {"kind": "list" | "agreed" | "free", "amount": "49.00"}}; agreed may also carry tiers |
allowance | {"kind": "stated", "allowance": {"included": "1000", "rollover": false}} |
cadence | {"kind": "stated", "cadence": {"kind": "every_period" | "once" | "on_event"}} |
timing | {"kind": "stated", "timing": "in_advance" | "in_arrears" | "phase_in_advance"} |
track | {"kind": "stated", "track": "pinned" | "follow"} |
version_change | {"kind": "stated", "version_change": "immediate_prorate" | "next_period" | "at_phase_change"} |
A value has three states, and the difference matters:
- stated (
"kind": "stated") sets the value on this phase and every later phase, until something else is stated. - reset (
"kind": "reset") drops back to the catalog origin and is stored, so a later phase does not re-inherit an agreed value from an earlier one. - absent (inherit) says nothing: the value is looked up further down the ladder.
The ladder is the order a value is resolved in: (1) stated on this phase's
line, (2) carried from the same line in an earlier phase, (3) the catalog origin
(for example the plan's default quantity and list price), (4) the subscription's
default. GET …/revisions/live returns every resolved value with the rung it
came from (1 to 4, 0 when unresolved) and, for rungs 1 and 2, stated_in_phase,
so you can see what the deal says and what merely follows the catalog. The older
chip field is deprecated and removed on 2026-11-30.
A line whose quantity resolves to nothing on any rung cannot be billed; state a
quantity on it unless its plan supplies a default. A quote carrying such a line
is refused when it is submitted or sent (SUBSCRIPTION_LINE_QUANTITY_MISSING).
Metered lines take their quantity from the meter.
Create and start a subscription
Three calls: create the envelope, author revision 1, activate.
POST /v1/subscriptionstakes onlycustomer_id(required),name,currency,on_early_stopandtranslations. It returns aDRAFTsubscription holding an empty draft revision 1. There is no plan, item, phase or interval field on create.PUT /v1/subscriptions/{id}/revisions/draftwrites every phase of revision 1 in one statement. It replaces whatever the draft held, so sending the same body twice gives the same draft; it needs noIdempotency-Key. The same call writes every later draft too (see Editing a draft).POST /v1/subscriptions/{id}/activatepublishes revision 1 and sets the subscriptionACTIVE. It emitssubscription.revision_published. It refuses withSUBSCRIPTION_NOT_DRAFTwhen the subscription has already started andSUBSCRIPTION_NO_DRAFTwhen nothing is parked on it.
A draft that a sent quote holds cannot be activated, published or discarded
directly (409 SUBSCRIPTION_DRAFT_ON_OFFER): the buyer's signature does that.
Currency
currency is set on create and defaults to EUR. Every amount on the
subscription is in it, and there is no field or endpoint that changes it later.
When the catalog has no price in that currency, the catalog price is converted
into the deal's currency (the line's catalog_price.converted_from says so). See
Exchange rates.
A customer's preferred_currency does not re-denominate existing subscriptions.
To move a customer to another currency, cancel the subscription and create a new
one with the currency you want; see
Customers.
Worked example
A 14-day free trial from 1 November 2026, then 10 seats at list price, open-ended. Later the customer goes to 25 seats, then gives notice for the end of the period, then changes their mind.
The ids below are placeholders: customer 0f8fad5b-d9cb-469f-a165-70867728950e,
plan 7c9e6679-7425-40de-944b-e07fc1f90ae7 (version 3), product
3b241101-e2bb-4255-8caf-4136c566a962, and the subscription the first call returns,
5d0b6a0e-8a4c-4b6e-9c51-2f7e3c1a9d40.
1. Create the envelope
cURL
Response 201 (abridged)
2. Author revision 1
Two phases: the trial states the quantity and a free price; the paid phase
states the quantity again and resets the price to the catalog's list price.
cURL
The response is the draft revision (number: 1, status: "draft"), with each
line's resolved values and, where it can be computed, its amount. Read it back
any time with GET /v1/subscriptions/5d0b6a0e-8a4c-4b6e-9c51-2f7e3c1a9d40/revisions/draft.
3. Activate
cURL
The subscription is now ACTIVE, and revision 1 is live. Until 2026-11-30 the
answer of activate, pause, resume and cancel is a wrapper around the
deal (revision, has_draft, live_number, …); every field of that wrapper is
deprecated. From 2026-11-30 the answer's data is the subscription itself. To
be ready for both, read the result with
GET /v1/subscriptions/{id}?include=revisions,actions.
4. Later: change the quantity from 1 February
A change to a live deal takes three calls: cut the live revision where the
change starts, write the whole draft with PUT …/revisions/draft,
publish.
4a. Cut at 1 February
The cut opens draft revision 2. Phases before the instant are kept. The phase
that contains the instant is split: its elapsed part now ends at 1 February
and says then: "stop". Everything after the instant is superseded (kept for
history):
Response 201 (abridged)
Now write the whole draft: the two kept phases as they are, with then: "next"
on the elapsed part, and the new phase with 25 seats. The new phase continues
the paid phase ("continues": true): it is the rest of the phase the cut
divided.
4b. Write the draft
The new phase states only the quantity. Its price is not stated, so it is inherited from the paid phase (the catalog's list price).
Response 200 (abridged)
4c. Publish
Publishing checks the draft whole (no gaps, no overlaps, every rule of the
model), makes it the live revision 2, supersedes revision 1 and emits
subscription.revision_published.
5. Cancel at the end of the billing period
cURL
The status stays ACTIVE until the planned instant. Read the plan back on the
subscription:
cURL
Response 200 (abridged)
scheduled_cancellation is absent when no cancellation is planned. It replaces
pending_cancel in the answer of the cancel call, which is deprecated and
removed on 2026-11-30.
6. Undo the scheduled cancellation
cURL
Answers 204. It is a no-op when no cancellation is pending, and it never
changes the status.
Changing a live deal
Every change to what is billed is a new revision. There are two ways to open one:
| You want to | Open the draft with | Then |
|---|---|---|
| Change something from an instant on: quantity, price, plan, product mix | POST /v1/subscriptions/{id}/revisions/cut with at (omitted, it is the current time; never in the past) | Write the whole draft with PUT …/revisions/draft, publish |
| Change a phase that has not started yet, or end a running phase at a date | POST /v1/subscriptions/{id}/revisions/draft (copies the live revision) | Write the whole draft with PUT …/revisions/draft, publish |
Only one draft can be open at a time (409 SUBSCRIPTION_DRAFT_OPEN); send
"replace_draft": true on the cut to discard an open draft and cut anyway.
Editing a draft
| Task | Endpoint |
|---|---|
| Read the open draft | GET /v1/subscriptions/{id}/revisions/draft |
| Write the whole draft | PUT /v1/subscriptions/{id}/revisions/draft |
| Price a draft without saving it | POST /v1/subscriptions/{id}/revisions/draft/preview |
| Publish | POST /v1/subscriptions/{id}/revisions/draft/publish |
| Throw the draft away | DELETE /v1/subscriptions/{id}/revisions/draft |
PUT …/revisions/draft states what the draft contains: its reason and
every active phase, in order. Each phase has the fields of a phase in
Phases plus its lines. The server works out the change and checks
the result. To add, remove, divide or reorder phases, or to change a value on a
line, send the whole draft with the change in it. Sending the same body twice
gives the same draft, so the PUT needs no Idempotency-Key. Phases that a cut
superseded are kept as history; you do not send them.
The easiest way to build the body is to read the draft
(GET …/revisions/draft), take its active phases, and change what you need.
For each line, send product_id, origin, price_key (when it has one) and
its stated values as values.
The rules a draft must keep:
- A phase that has started (it opened before the draft was opened and
before now) cannot change. Only its
endsandthenmay change, and its new end may not be before now. Removing it, or putting a phase before it, is a change. - To change the deal from a date inside a phase, end that phase at the date
and add the next phase with
"continues": true. The new phase is then the rest of the same phase, as a split leaves it: a line whoseversion_changeisat_phase_changekeeps its version across the date, and an event end is measured from the first part's start. continuesneeds a phase that startsafter_previous, after a phase that ends on a date or after a length. The first phase continues nothing.- When a phase leaves
continuesout, it keeps what the draft says for the phase at the same position. A new phase right after the elapsed part of a cut continues it. Send"continues": falsefor a phase that is a new deal, for example another plan. thenisnextwhen a phase follows, andopenorstoponly on the last phase.- One line per product and price key in a phase.
- The draft must not be held by a quote that is out with the customer (
409 SUBSCRIPTION_DRAFT_ON_OFFER).
With no open draft, the PUT is refused with 409 SUBSCRIPTION_NO_DRAFT: open one
with a cut or with POST …/revisions/draft first.
POST /v1/subscriptions/{id}/revisions/draft/phases (append one phase) is
deprecated and removed on 2026-11-30. Send the whole draft with the new phase in
it instead. The single-phase and single-value operations the dashboard uses are
not part of the public API.
Example: 15 seats from 1 April
On 10 March, the customer from the worked example agrees to 15 seats at an agreed €39.00 from 1 April. The phase in force has started, so it stays as it is; only its end moves to 1 April, and a new phase continues it.
1. Open a draft
The answer is draft revision 3, a copy of the live revision 2. Now write the whole draft. The first two phases are sent as they are. Phase 3 (25 seats) now ends on 1 April, and phase 4 continues it with 15 seats at the agreed price:
2. Write the draft
Response 200 (abridged)
3. Publish
The agreed price holds for this phase and every later one until something else
is stated. {"kind": "reset"} goes back to the catalog's list price.
Price a draft before you write it
POST …/revisions/draft/preview takes the same body as the PUT and answers the
revision the PUT would leave, with every value resolved and every line priced.
Nothing is saved. Use it to show the new amounts before you commit them; in
the example above it answers the same €585 per month for phase 4.
cURL
draft.json holds the same body as the PUT. The preview needs only the
subscription.read scope.
When a draft is refused
A refused write lists every problem at once, in problems. Each item has:
| Field | What it carries |
|---|---|
pointer | A JSON pointer into your body, for example /phases/2/ends. |
phase | The phase's position (0-based), when the problem is about one phase. |
line | product_id and price_key, when the problem is about one line. |
code | The rule's own code, for example SUBSCRIPTION_PHASE_THEN. |
message | A sentence that says what to change. Phases are counted from 1 here. |
For example, the same PUT with phase 3 ending on 1 March (before now, 10 March)
and then: "next" on the last phase:
Response 422
Branch on each item's code; message is for people and its wording can
change. A refusal about the state of the subscription (no open draft, a draft
held by a quote) is a single 409, without problems.
The PUT on revision 1 (before the subscription starts) also lists problems,
but until 2026-11-30 its top-level code is the first problem's own code. From
2026-11-30 it is SUBSCRIPTION_DRAFT_INVALID, as for every later draft.
Change the plan
A line belongs to the plan or product version named in its origin. To move a
customer to another plan from an instant, cut there and write the draft with a
new last phase whose lines name the new plan in origin (and the products that
plan carries). Plans
of two different billing cadences cannot share one paid phase (422 SUBSCRIPTION_CADENCE_MISMATCH), but a later phase may change the cadence, for
example monthly then annual.
When a change is invoiced
What the change is decides when the money moves:
| The change | Invoiced |
|---|---|
Another plan or product, or a line added, removed or given another timing | At the change, on an invoice of its own: a credit of what the replaced lines already billed for the rest of the period, and the new lines from the change to the period's end. The billing period does not move. |
Another quantity or price on the same lines | On the next invoice (the end of the current period): a credit of what was billed ahead and a charge of the new terms, for the days since the change. |
| A change of billing cadence (monthly to annual) | At the change: the current period ends there and the new cadence starts. |
A change "from now" (a cut without at) is invoiced within seconds of the
publish, and the invoice is collected like any other: invoice.finalized
follows, and a customer with a saved payment method is charged. When the
credit comes to more than the charge (a downgrade), the difference goes on a
credit note of the invoice that billed the period. live.next_cut_at on the
subscription names the change until its invoice is written.
Worked example: a yearly plan of €468.00 for 10 seats, moved to a €588.00 plan exactly half way through the year (183 of 366 days left). The invoice at the change credits €234.00 and charges €294.00: €60.00 net, before tax. A customer who later cancels is not billed that half year again.
Following new catalog versions
Whether a line moves to a newer version of its plan or product when one is
published is the line's own track value: follow moves it, pinned keeps the
version in origin. When a following line moves is its version_change value
(immediate_prorate, next_period or at_phase_change), falling back to the
plan's default_version_change. The subscription's live.effective_track
(follow, pinned or mixed) summarises the lines of the phase in force.
Before you publish a plan, GET /v1/plans/{id}/publish-impact tells you which
subscriptions would move. See Versioning.
Billing periods
The deal decides the calendar; the subscription reports it. current_period
and next_cut_at are read under live (include=live).
| Field | Meaning |
|---|---|
cadence | {"unit": "week" | "month" | "year", "count": n}: how often periods repeat. Taken from the plans of the paid phase. |
alignment | Where periods fall: start (from the first paid phase's start), day_of_month with day 1–28, or last_day. Taken from the plan's billing_alignment (else the organization's default) when the deal first goes live with a paid phase, and never changed afterwards. |
live.current_period | {start, end}, half-open. Absent for a draft, during a trial before the first paid phase, and for a deal with no paid phase. |
live.next_cut_at | When the next invoice is written: the end of the current period, or an earlier change of plan that is still to be invoiced. |
When a line is invoiced is its timing value: in_advance at the start of
each period, in_arrears at its end, or phase_in_advance (the whole phase in
one invoice at its opening). A line that states none takes the plan's
default_timing, else in_arrears. Usage is always billed in arrears.
While any of the subscription's invoices is overdue, its next invoice is held
(billing_state.overdue_invoices, held_since, retry_at) until they are
paid. See Dunning.
Pause and resume
Pause
Resume
Both take an optional at (defaults to now) and reason. Only an ACTIVE
subscription pauses; only a PAUSED one resumes.
Pausing sets the status to PAUSED and freezes the phase clocks. Resuming
shifts the live revision by the paused time and publishes the result as a new
revision, then returns the status to ACTIVE: a 12-month phase is still 12
months of service. Fixed dates move too; actions.pause_moves_dates on the
subscription (include=actions) lists the fixed dates a pause would move. Because the shift is a revision of its own,
an open draft blocks the resume (409 SUBSCRIPTION_DRAFT_OPEN): publish or
discard it first.
Pause and resume emit subscription.paused and subscription.resumed, plus
subscription.status_changed. To pause or resume on a future date, schedule it
(see Scheduling).
Cancel
POST /v1/subscriptions/{id}/cancel takes when and an optional reason:
when | Effect |
|---|---|
{"kind": "now"} (the default when when is omitted) | Ends the subscription now. If a cancellation was already planned, that one is applied instead of a second. |
{"kind": "at", "at": "2027-06-30T00:00:00Z"} | Plans the cancellation for a future instant. A past instant is refused (422 SUBSCRIPTION_CANCEL_IN_PAST). |
{"kind": "period_end"} | Plans it for the end of the billing period in force, resolved once when you call. Refused with 409 SUBSCRIPTION_CANCEL_NO_PERIOD when no period is in force (a draft, a trial before its first paid phase). |
A planned cancellation is read back as scheduled_cancellation (at,
reason, created_by_id, created_at) on the subscription
(include=scheduled_cancellation), and withdrawn with
DELETE /v1/subscriptions/{id}/scheduled-cancellation.
When it takes effect the status becomes CANCELLED with cancellation_reason
USER_REQUEST, and subscription.cancelled, subscription.stopped and
subscription.status_changed are emitted. What happens to the unused part of
a period that was billed in advance is the deal's on_early_stop:
no_credit keeps it billed, credit_unused credits it on the closing invoice.
When the subscription states none, the plan version's default applies, else
no_credit.
Exit rules can refuse a cancellation
The phase in force at the instant the cancellation would take effect can carry
exit rules. A block gate with a not_before phase that has not ended refuses
the cancellation with 409 SUBSCRIPTION_EXIT_BLOCKED, both for now and when
you plan one with at or period_end. See
Commitments and exit rules.
The EU right of withdrawal for consumers is available through the customer
portal; it is not part of the public API. If your own application takes the
withdrawal, do it in two calls: end the subscription at once
(POST /v1/subscriptions/{id}/cancel with when now), then refund what the
customer paid less the value of what they already used
(POST /v1/invoices/{id}/refund with amount and reason
requested_by_customer). The refund writes the credit note.
Scheduling a change for later
Instead of acting now, you can schedule an operation with
POST /v1/changes (see Scheduled changes). For subscriptions:
| Operation | What it does |
|---|---|
subscription.set_status | payload.kind stop_at (cancel at payload.from), pause or resume |
subscription.transform | Rewrites line values or exit rules from payload.from on and publishes the result as a new revision |
subscription.apply_for_a_while | The same rewrites as a transform, held only from payload.from until until (or for for_count × for_unit) |
subscription.set_default | Changes the subscription's defaults: payment_terms_days, the default track and the default version_change |
GET /v1/changes/operations lists each operation with its payload schema and
the when kinds it accepts. For example, pause on 1 March 2027 in Berlin time:
cURL
at is a wall-clock time read in zone; send it with a Z suffix and name the
zone separately. Cancel a scheduled change with DELETE /v1/changes/{id}.
A transform leaves agreed values alone
A set_value transform does not overwrite a value the deal agreed (stated on
the phase, or carried from an earlier phase); it reports those lines as skipped
in its preview. To change an agreed value, open a draft with a cut and write
it with PUT …/revisions/draft, as above.
Quotes: the other way in
When the deal needs the customer's signature, start from a quote:
POST /v1/quoteswithkind: "NEW_SUBSCRIPTION"and thecustomer_id.POST /v1/quotes/{id}/revisionswith{"kind": "new"}mints aDRAFTsubscription and returns itssubscription_id. For an existing customer deal,{"kind": "renegotiation", "subscription_id": …, "cut_at": …}cuts its live revision instead.- Author that subscription's draft revision with the same operations as above
(
PUT …/revisions/draft, andPOST …/revisions/draft/previewto price it). - Send the quote. Signing publishes the revision and, for a new subscription,
activates it.
GET /v1/quotes/{id}/signabilitychecks in advance whether a sent quote can still be signed.
Subscribe in the dashboard
Over the API, these are the three calls in Create and start a subscription.
-
Open the subscriptions list
In the sidebar under Billing, click Subscriptions, or press G then S.
-
Start the subscription
Click Create Subscription, then pick the customer and the plan.
Customer first, then plan -
Shape the phases
Add a trial if there is one, set the quantities the customer bought, and any agreed prices. This writes the draft revision.
-
Activate it
A subscription is created as
DRAFTand bills nothing until it is activated.
Operations at a glance
| Task | Operation |
|---|---|
Create (empty DRAFT) | POST /v1/subscriptions |
| Write a draft whole (revision 1 or a later draft) | PUT /v1/subscriptions/{id}/revisions/draft |
| Start | POST /v1/subscriptions/{id}/activate |
| Read the deal | GET /v1/subscriptions/{id}/revisions/live |
| Read period, next cut and MRR | GET /v1/subscriptions/{id}?include=live |
| Open a change from an instant | POST /v1/subscriptions/{id}/revisions/cut |
| Open a correction | POST /v1/subscriptions/{id}/revisions/draft |
| Price a draft without saving it | POST /v1/subscriptions/{id}/revisions/draft/preview |
| Make the draft live | POST /v1/subscriptions/{id}/revisions/draft/publish |
| Pause / resume | POST /v1/subscriptions/{id}/pause, POST /v1/subscriptions/{id}/resume |
| Cancel now, at a date, or at period end | POST /v1/subscriptions/{id}/cancel |
| Undo a planned cancellation | DELETE /v1/subscriptions/{id}/scheduled-cancellation |
| Rename, describe, custom fields | PATCH /v1/subscriptions/{id} |
| Price a candidate plan without a subscription | POST /v1/subscriptions/preview |
| Schedule any of this for later | POST /v1/changes |
Events
| Event | When |
|---|---|
subscription.created | The envelope is created. |
subscription.activated | It becomes ACTIVE. |
subscription.revision_published | A revision goes live (activation, publish, resume, a signed quote). |
subscription.phase_entered | A phase's window opens. |
subscription.paused / subscription.resumed | Pause and resume. |
subscription.status_changed | Any move between active, paused and cancelled. |
subscription.cancelled / subscription.stopped | It ends; stopped carries which kind of ending. |
See Webhooks and events.
Next step
Continue to Invoices to see what this subscription produces.
Reference
| Topic | When you need it |
|---|---|
| Commitments and exit rules | Minimum terms, notice and early-exit rules on a phase |
| Quotes | Selling a deal that needs a signature |
| Scheduled changes | Changes that take effect later |
| Versioning | How plan and product versions are published, and what follows them |
| Currencies | The money wire format |
| Exchange rates | What happens when the catalog does not price the deal's currency |
| Dunning | What happens to a subscription whose invoices stop being paid |
| Usage | Metered lines and how their quantity is arrived at |
| Subscriptions API | Every field and operation |