v1

latestOpenAPI 3.1.02026-07-222392081.7 MB

Subscriptions > Transitions

Create subscription transition

Transition a subscription to another subscription, configured from a subscription, a plan or a template. If the application_schedule is immediately, the transition is applied right away.

post/v2/subscriptions/transitions

Request body

source_subscription_idstring required

The ID of the subscription to transition from

namestring

An optional name for the transition

calculation_method'do_not_charge' | 'pro_rata' | 'refund_and_reinvoice'

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.

billing_cycle_transition_method'keep_current_billing_cycle' | 'align_to_new_billing_cycle'

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.

application_schedule'scheduled' | 'immediately' | 'last_renewal' 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.

transition_datestring date-time

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 format.

Example request

{
  "transition_date": "2024-12-20T16:04:11Z",
  "target_subscription": {
    "invoicing_entity_id": "ive_jerrb484RHn",
    "commitment_interval": {
      "period": "years",
      "count": 1
    },
    "renew_for": {
      "period": "years",
      "count": 1
    },
    "minimum_invoice_fee": 250,
    "contract_terms": {
      "starts_at": "2024-12-20T16:04:11Z",
      "ends_at": "2024-12-20T16:04:11Z",
      "duration": {
        "count": 6,
        "period": "months"
      },
      "renew_for_duration": {
        "count": 1,
        "period": "years"
      },
      "activation_strategy": "start_date",
      "end_strategy": "duration"
    },
    "starts_at": "2024-12-20T16:04:11Z",
    "contract_start": "2024-01-15T00:00:00Z",
    "contract_end": "2025-01-15T00:00:00Z",
    "initial_billing_at": "2024-12-20T16:04:11Z",
    "cancel_at": "2024-12-20T16:04:11Z",
    "plan_id": "plan_zHmjoDee4ZRmQV",
    "template_id": "subt_7gdusOkqr5L0B8",
    "template_configuration_id": "subtc_7mHWOlPStUogvp",
    "phases": [
      {
        "name": "Initial term",
        "type": "standard",
        "status": "pending",
        "activation_strategy": "manual",
        "end_strategy": "duration",
        "duration": {
          "count": 1,
          "period": "years"
        },
        "billing_date_setting": "phase_start",
        "initial_billing_at": "2024-12-20T16:04:11Z",
        "starts_at": "2024-12-20T16:04:11Z",
        "ends_at": "2024-12-20T16:04:11Z",
        "billing_cycle_alignment": "anniversary",
        "transition_calculation_method": "prorata",
        "transition_invoicing_schedule": "immediately",
        "products": [
          {
            "id": "itm_FJKlqUb8COXw55",
            "name": "Product name",
            "description": "A description of the product.",
            "payment_interval": {
              "period": "once"
            },
            "payment_schedule": "start",
            "price": {
              "type": "fee",
              "amount": 200
            },
            "prices": [
              {
                "type": "volume",
                "from": 0,
                "to": 20,
                "amount": 200,
                "unit_count": 1,
                "on_tier_incomplete": null
              },
              {
                "type": "volume",
                "from": 20,
                "to": null,
                "amount": 150,
                "unit_count": 1,
                "on_tier_incomplete": null
              }
            ],
            "count": 2,
            "unit_name": "user"
          }
        ],
        "coupons": [
          {
            "expires_at": "2024-12-20T16:04:11Z",
            "apply_at": "2024-12-20T16:04:11Z"
          }
        ]
      }
    ]
  }
}

Response

idstring required

The unique identifier of the subscription transition

customer_idstring required

The ID of the customer associated with the transition

base_subscription_idstring required

The ID of the original subscription from which this transition is derived. It references the last active version of the subscription.

source_subscription_idstring required

The ID of the subscription to transition from

target_subscription_idstring nullable required

The ID of the subscription to transition to

The current status of the subscription transition. Possible values are 'scheduled', 'completed', 'failed', and 'draft'.

transitioned_atstring 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 format.

namestring nullable required

An optional name for the transition

transition_datestring date nullable required

billing_cycle_transition_method'keep_current_billing_cycle' | 'align_to_new_billing_cycle' nullable required

calculation_method'do_not_charge' | 'pro_rata' | 'refund_and_reinvoice' nullable required