API ReferenceSubscriptions

Pause Subscription

View as Markdown
Pause a subscription with optional auto-resume. Supports two mutually exclusive pause modes: - **pause_for_cycles**: Number of billing cycles to pause. The system calculates resumes_at based on billing cycle duration. - **resumption_date**: Explicit datetime when subscription should auto-resume. If neither is provided, the subscription is paused indefinitely until manually resumed. When paused with a resumes_at date (either calculated or explicit), the Restate workflow will automatically resume the subscription at the specified time. Emits `subscription.paused` webhook event with: - paused_at: When the subscription was paused - resumes_at: When it will auto-resume (if set) Works for both User and API Key authentication. Account access is automatically validated via endpoint dependency.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

subscription_idstringRequired
account_idstringRequired

Request

This endpoint expects a nullable object.
pause_behaviorenumOptional

When to activate the pause (immediately or at period end)

pause_for_cyclesinteger or nullOptional>=1

Number of billing cycles to pause for. Mutually exclusive with resumption_date.

resumption_datedatetime or nullOptional

Explicit datetime when subscription should auto-resume. Mutually exclusive with pause_for_cycles.

Response

Successful Response
idstring
stateenum

The possible states of a subscription.

Most are self-explanatory: it starts INCOMPLETE (created, not yet paid for), or TRIALING / SCHEDULED, becomes ACTIVE once paid, and can end up PAUSED, PAST_DUE (a payment failed), or CANCELLED.

ACTIVE_UNSETTLED is the unusual one, added for slow bank rails like SEPA where the money does not arrive until days later. It means: “we already let the customer in at checkout, but their payment has not actually settled yet.” A subscription is created straight into this state — nothing ever moves INTO it from another state. It has exactly two ways out: it becomes ACTIVE if the payment settles, or CANCELLED if the payment fails, times out, or is later reversed (a chargeback).

currencyenum
ISO 4217 currency codes.
descriptionstring or null
current_period_startdatetime
current_period_enddatetime
trial_startdatetime or null
trial_enddatetime or null
created_atdatetime
updated_atdatetime
itemslist of objects
customerobject
collection_methodenum
payment_methodobject or null
Payment method API response model.
billing_intervalstring or nullOptional
billing_interval_countinteger or nullOptional
paused_atdatetime or nullOptional
resumes_atdatetime or nullOptional
pause_at_endboolean or nullOptional
cancel_at_period_endboolean or nullOptional
cancel_atdatetime or nullOptional
cancellation_refund_optionenum or nullOptional

Refund options when cancelling a subscription.

  • NONE: Cancel with no refund (current behavior)
  • FULL: Refund full current period amount
  • PRORATED: Refund unused portion of current period
  • CANCEL_UNPAID: Use dunning_end_behavior for unpaid invoices
cancellation_detailsobject or nullOptional

Details about why a subscription was cancelled.

All fields are optional — callers can provide any combination. Stored as JSONB on the subscription entity.

net_dinteger or nullOptional
statement_descriptor_suffixstring or nullOptional
Statement descriptor suffix for this subscription.
total_billing_cyclesinteger or nullOptional
remaining_billing_cyclesinteger or nullOptional
contract_auto_renewboolean or nullOptional
discountobject or nullOptional
Response schema for discount data.
last_successful_processor_idstring or nullOptional
metadatamap from strings to any or nullOptional
split_from_subscriptionstring or nullOptional

ID of the subscription this was split from (cross-interval plan change).

split_to_subscriptionslist of strings or nullOptional

IDs of subscriptions created from this one (cross-interval plan change).

pending_plan_changeobject or nullOptional
Pending plan change scheduled for period end. Present when a deferred plan change is awaiting execution.
custom_fieldsmap from strings to any or nullOptional

Custom field values. Only included when expand=custom_fields is specified.

Errors

422
Unprocessable Entity Error