---
title: "List subscription transitions"
method: GET
path: "/v2/subscriptions/transitions"
tags: ["Subscriptions > Transitions"]
---

# List subscription transitions

`GET /v2/subscriptions/transitions`

Retrieve existing subscription transitions.

## Query parameters

- `take` number, nullable
- `skip` number, nullable
- `status` union
  - 'scheduled' | 'draft' | 'completed' | 'cancelled' | 'failed' | 'pending_quote_signature'
  - string — scheduled,draft
- `status__in` union
  - 'scheduled' | 'draft' | 'completed' | 'cancelled' | 'failed' | 'pending_quote_signature'
  - string — scheduled,draft
- `source_subscription_id` string
- `source_subscription_id__not` string
- `source_subscription_id__isNull` string
- `source_subscription_id__isNotNull` string
- `source_subscription_id__equals` string
- `source_subscription_id__contains` string
- `source_subscription_id__startsWith` string
- `source_subscription_id__endWith` string
- `base_subscription_id` string
- `base_subscription_id__not` string
- `base_subscription_id__isNull` string
- `base_subscription_id__isNotNull` string
- `base_subscription_id__equals` string
- `base_subscription_id__contains` string
- `base_subscription_id__startsWith` string
- `base_subscription_id__endWith` string
- `target_subscription_id` string
- `target_subscription_id__not` string
- `target_subscription_id__isNull` string
- `target_subscription_id__isNotNull` string
- `target_subscription_id__equals` string
- `target_subscription_id__contains` string
- `target_subscription_id__startsWith` string
- `target_subscription_id__endWith` string
- `transition_date` string, date-time
- `transition_date__not` string, date-time
- `transition_date__isNull` string, date-time
- `transition_date__isNotNull` string, date-time
- `transition_date__equals` string, date-time
- `transition_date__lt` string, date-time
- `transition_date__lte` string, date-time
- `transition_date__gt` string, date-time
- `transition_date__gte` string, date-time
- `transitioned_at` string, date-time
- `transitioned_at__not` string, date-time
- `transitioned_at__isNull` string, date-time
- `transitioned_at__isNotNull` string, date-time
- `transitioned_at__equals` string, date-time
- `transitioned_at__lt` string, date-time
- `transitioned_at__lte` string, date-time
- `transitioned_at__gt` string, date-time
- `transitioned_at__gte` string, date-time

## Response `200`

- PaginatedSubscriptionTransition
  - `meta` object, required
    - `total` number, required — Total of existing items.
    - `taken` number, required — Number of items returned.
    - `skipped` number, required — Number of items skipped.
  - `data` object[], required — List of SubscriptionTransition.
    - `id` string, required — The unique identifier of the subscription transition
    - `customer_id` string, required — The ID of the customer associated with the transition
    - `base_subscription_id` string, required — The ID of the original subscription from which this transition is derived. It references the last active version of the subscription.
    - `source_subscription_id` string, required — The ID of the subscription to transition from
    - `target_subscription_id` string, nullable, required — The ID of the subscription to transition to
    - `status` 'scheduled' | 'completed' | 'failed' | 'draft' | 'cancelled' | 'pending_quote_signature', required — The current status of the subscription transition. Possible values are 'scheduled', 'completed', 'failed', and 'draft'.
    - `transitioned_at` string, date, nullable, required — The date and time when the transition was completed. Null if the transition is not yet completed. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
    - `name` string, nullable, required — An optional name for the transition
    - `transition_date` string, date, nullable, required — The date at which the transition should occur. Only applicable if the application schedule is 'scheduled'. Can be a past date within the current billing period. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
    - `application_schedule` 'immediately' | 'scheduled' | 'next_renewal' | 'last_renewal' | 'quote_signature' | 'scheduled_after_quote_signature', required — When the transition should be applied: 'immediately', 'scheduled' for a specific date, or 'last_renewal' to apply it retroactively to the start of the current billing period (refunding what was already invoiced for that period and re-charging the new configuration). Past dates within the current billing period are supported and will be applied immediately.
    - `billing_cycle_transition_method` 'keep_current_billing_cycle' | 'align_to_new_billing_cycle', nullable, required — The billing cycle transition method to use. 'keep_current_billing_cycle' will keep the current billing cycle dates if possible. 'align_to_new_billing_cycle' will align the billing cycle to the transition date.
    - `calculation_method` 'do_not_charge' | 'pro_rata' | 'refund_and_reinvoice', nullable, required — The calculation method to use for the transition. 'do_not_charge' will not generate any transition invoice. 'pro_rata' will generate a prorated invoice for the remaining period. 'refund_and_reinvoice' (only available with application_schedule 'last_renewal') issues a credit note for what was invoiced for the current period and a separate invoice for the new configuration.

---

[API](https://skmtc.dev/hyperline/apis/hyperline-api.md) · [All operations](https://skmtc.dev/hyperline/apis/hyperline-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hyperline/hyperline-api/revisions/19fa5f22e39b/schema)