Skip to main content
GET
Retrieve Subscription

Authorizations

public-api-key
string
header
default:<Your public-api-key>
required
private-secret-key
string
header
default:<Your private-secret-key>
required

Path Parameters

subscription_id
string
required

The unique identifier of the subscription.

Response

200

id
string
Example:

"7304911d-5df9-429e-8488-ad41abea1a4c"

name
string
Example:

"sub_001"

description
string
Example:

"streaming service"

account_id
string
Example:

"2404911d-5df9-429e-8488-ad41abea1a4b"

merchant_reference
string
Example:

"001_marzo_23"

soft_descriptor
string
Example:

"ACME SUBSCRIPTION"

status
string
Example:

"ACTIVE"

amount
object
frequency
object
billing_cycles
object
current_period_start
string

Only returned by this endpoint, and only once the first billing cycle has been charged. Always returned together with current_period_end.

Example:

"2023-01-16T20:00:00.912480Z"

current_period_end
string

Only returned by this endpoint, and only once the first billing cycle has been charged. Equal to billing_cycles.next_at. Always returned together with current_period_start.

Example:

"2023-02-16T20:00:00.786342Z"

customer_payer
object
payment_method
object
availability
object
trial_period
object
metadata
object[]
payments
string[]
subscription_agreement_id
string
Example:

"sa_6af2dfcd-44c0-4f16-a331-8bed3ed9c9fa"

plan_id
string

Only present when the subscription is linked to a plan.

Example:

"00000000-0000-4000-8000-000000000001"

plan_assigned_at
string

Only present on plan-linked subscriptions. The moment the plan was attached — at creation from a plan, migration onto a plan, or a plan change.

Example:

"2023-12-16T20:46:54.786342Z"

previous_subscription_id
string

Only present when this subscription was created by a plan change (switching an existing subscription to a different plan).

current_phase
string

Only present on plan-linked subscriptions.

Example:

"REGULAR"

billing_phases
object[]

Only present on plan-linked subscriptions whose plan has phases. Contains the leading TRIAL phases only, snapshotted at creation — the terminal REGULAR phase is never included, since its price isn't pinned and instead resolves from the plan at every billing. current_phase: "REGULAR" is how you know the ladder is exhausted.

pending_plan_change
object | null

The plan change scheduled for the next billing cycle, or null when none is pending. Schedule one with the plan_change block on Update Subscription.

created_at
string
Example:

"2023-12-16T20:46:54.786342Z"

updated_at
string
Example:

"2023-12-16T21:00:54.786342Z"