---
title: "Create subscription transition"
method: POST
path: "/v2/subscriptions/transitions"
tags: ["Subscriptions > Transitions"]
---

# Create subscription transition

`POST /v2/subscriptions/transitions`

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.

## Request body

- object
  - `source_subscription_id` string, required — The ID of the subscription to transition from
  - `name` string — 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_date` string, 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](https://en.wikipedia.org/wiki/ISO_8601) format.
  - `target_subscription` union, required
    - object — The configuration of the subscription to transition to
      - `name` string — Subscription custom name.
      - `purchase_order` string — Reference to the purchase order.
      - `invoicing_entity_id` string — ID of the invoicing entity attached to the subscription. If not defined, fallback to customer's invoicing entity.
      - `crm_opportunity_id` string — ID of the related opportunity/deal in the connected CRM.
      - `commitment_interval` object — Deprecated field, please use `contract_terms`.
        - `period` 'days' | 'weeks' | 'months' | 'years', required
        - `count` number, required
      - `renew_for` object — Deprecated field, please use `contract_terms`.
        - `period` 'days' | 'weeks' | 'months' | 'years', required
        - `count` number, required
      - `minimum_invoice_fee` number, nullable — Minimum fee applied to each invoice outside of one time payments.
      - `contract_terms` object — Contract terms linked to the subscription.
        - `starts_at` string, date-time — Start date of the contract. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        - `ends_at` string, date-time — End date of the contract. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        - `duration` object — Interval over which the contract initially spans. Only applies to `duration` end strategy.
          - `period` 'days' | 'weeks' | 'months' | 'years', required
          - `count` integer
        - `renew_automatically` union — Indicates if the contract should be renewed automatically. - `true`: The contract will be renewed automatically. - `false`: The contract will not be renewed automatically.
          - boolean
          - 'true' | 'false'
        - `renew_for_duration` object — Interval over which the contract will be renewed. Only applies if `renew_automatically` is true.
          - `period` 'days' | 'weeks' | 'months' | 'years', required
          - `count` integer
        - `activation_strategy` 'start_date' | 'immediately' | 'manual' | 'quote_signature' | 'checkout', required — Activation strategy of the contract. - `immediately`: The contract will be activated immediately. - `manual`: The contract will be activated when a user manually activates it. - `start_date`: The contract will be activated on a specified date. - `quote_signature`: The contract will be activated when the subscription quote is signed. - `checkout`: The contract will be activated when the subscription checkout is completed.
        - `end_strategy` 'end_date' | 'duration' | 'manual', required — End strategy of contract. - `manual`: The contract ends when a user manually stops it. - `end_date`: The contract ends on a specified date. - `duration`: The contract ends after a specific relative duration, unless `renew_automatically` is true.
      - `starts_at` string, date-time — Applies only if the activation strategy is `start_date`. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
      - `contract_start` string, date-time — Deprecated field, please use `contract_terms`.
      - `contract_end` string, date-time — Deprecated field, please use `contract_terms`.
      - `initial_billing_at` string, date-time — Date when the subscription will start being billed. If not specified, it will correspond to the `starts_at` date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
      - `display_shipping_details` union — Indicates if the shipping details should be displayed on the subscription's invoices.
        - boolean
        - 'true' | 'false'
      - `cancel_at` string, date-time — Subscription cancel date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
      - `cancellation_strategy` 'refund_prorata' | 'refund_custom' | 'charge_prorata' | 'charge_custom' | 'end_of_period' | 'do_nothing' — Strategy used to cancel the subscription. If not specified `do_nothing` is used. - `charge_prorata`: Will charge the customer the unpaid amount for the prorated period up to the end of the current period. - `charge_custom`: Will charge the customer a custom amount. - `refund_prorata`: Will refund to the customer the overpaid subscription amount using prorated calculations on the cancellation date. - `refund_custom`: Will refund to the customer a custom amount. - `end_of_period`: Will cancel the subscription at the end date of the current billing period. - `do_nothing`: Will only cease the subscription without any additional actions.
      - `cancellation_amount` number — Custom amount used when cancelling the subscription. Only applies to the `charge_custom` or the `refund_custom` cancellation strategy.
      - `cancellation_refund_method` 'wallet' | 'original_payment_method' | 'external' — Override the refund destination for credit notes generated by `refund_prorata` / `refund_custom` cancellation strategies. When omitted, falls back to the invoicing entity's `creditNoteWalletRefundEnabled` setting.
      - `properties` object — Key/value pairs to store any metadata useful in your context.
      - `custom_properties` object — A list of key value with the slug of the custom property as the key and the custom property value as value.
      - `tax_only` union — Only tax will be charged on this subscription.
        - boolean
        - 'true' | 'false'
      - `generate_draft_invoices` union — Generate draft invoices for the subscription. Each invoice will need to be reviewed and validated manually before being sent
        - boolean
        - 'true' | 'false'
      - `generate_document` union — Generate non-legal documents instead of invoices.
        - boolean
        - 'true' | 'false'
      - `document_name` string, nullable — If `generate_document` is turned on, allows you to give a name to your document.
      - `add_tax_to_document` union — If `generate_document` is turned on, will add taxes to document.
        - boolean
        - 'true' | 'false'
      - `do_not_charge_subscription` union — Subscription will be invoiced but not charged (invoices/documents will be settled directly).
        - boolean
        - 'true' | 'false'
      - `invoice_custom_note` string, nullable — Default custom note added to invoices generated by the subscription.
      - `invoice_schedule` 'period_start' | 'period_end', nullable — Defines when invoices are generated relative to the billing period. - `period_start`: Invoices are generated at the start of the billing period. - `period_end`: Invoices are generated at the end of the billing period.
      - `plan_id` string — Deprecated field, please use `template_id`.
      - `template_id` string — ID of the template that the subscription is linked to.
      - `template_configuration_id` string — ID of the template configuration that the subscription is linked to.
      - `phases` object[], required
        - `name` string — Name of the subscription phase.
        - `type` 'setup' | 'trial' | 'standard' — Type of subscription phase. - `setup`: The phase represents a non-recurring service setup period, often used before the actual recurring subscription begins. - `trial`: The phase represents a non-recurring trial period, often used to allow users to opt out or experience a free test. - `standard`: The phase represents a standard recurring billing.
        - `status` 'finished' | 'pending' — Status of subscription phase. - `pending`: The phase is waiting to start (not started yet). - `active`: The phase is currently in progress. - `finished`: The phase has ended and is complete.
        - `order` number — Order in which the phase is executed within all subscription phases.
        - `activation_strategy` 'immediately' | 'manual' | 'start_date' | 'quote_signature' | 'checkout' | 'contract_start_date' | 'previous_phase_end', required — Activation strategy of subscription phase. - `immediately`: The phase starts as soon as the subscription is activated. - `manual`: The phase starts when a user manually activates it. - `start_date`: The phase starts on a specified date. - `quote_signature`: The phase starts when the subscription quote is signed. - `checkout`: The phase starts when the subscription checkout is completed. - `contract_start_date`: The phase starts on the start date of the related subscription contract. - `previous_phase_end`: The phase starts when the previous phase ends.
        - `end_strategy` 'manual' | 'end_date' | 'duration' | 'contract_end_date', required — End strategy of subscription phase. - `manual`: The phase ends when a user manually stops it. - `end_date`: The phase ends on a specified date. - `duration`: The phase ends after a specific relative duration. - `contract_end_date`: The phase ends on the end date of the related subscription contract.
        - `duration` object — Interval over which the subscription phase spans. Only applies to `duration` end strategy.
          - `period` 'days' | 'weeks' | 'months' | 'years', required
          - `count` integer
        - `billing_date_setting` 'phase_start' | 'specific_date', required — Represents when the first billing date occurs. - `phase_start`: Aligns with the start of the phase. - `specific_date`: Occurs on a specified date.
        - `initial_billing_at` string, date-time — Date when the subscription phase will start being billed. Only applies to `specific_date` billing date setting. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        - `starts_at` string, date-time — Actual start date of the phase. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        - `ends_at` string, date-time — Actual end date of the phase. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        - `billing_cycle_alignment` 'calendar_period' | 'anniversary' — Alignment of product billing cycles. - `calendar_period`: The billing cycles of the products will be aligned on the calendar period, after the first period which will be invoiced taking into account the prorata of the first cycle compared to the product periodicity. - `anniversary`: The billing cycles of the products will be aligned on the anniversary of the phase initial billing date.
        - `do_not_invoice_phase` boolean — Indicates if the phase should be invoiced. If set to true, the phase will not generate any invoices.
        - `transition_calculation_method` 'prorata' | 'pay_in_full' | 'none' — Calculation method used when transitioning from one phase to the next one. - `prorata`: The prorated amount between the two phases relative to the end date (the transition date) must be paid. - `pay_in_full`: The full amount for the phase billing period must be paid. - `none`: No amount will need to be paid, phase will simply transition from one to the next.
        - `transition_invoicing_schedule` 'immediately' — Represents when the transition amount will be invoiced. - `immediately`: An invoice will be generated immediately with the corresponding amount.
        - `products` object[], required — Products comprising the subscription phase.
          - `id` string, required — Product ID.
          - `name` string — Product name. This will appear on the final invoices.
          - `description` string — Product description. This will appear on the final invoices.
          - `description_display_interval_dates` boolean — Indicates if the dates of the interval should be automatically added in the product description on the invoices.
          - `payment_interval` union — Interval on which the product is billed. This interval can be different between products and can differ from the subscription commitment interval.
            - object
              - …
            - object
              - …
          - `payment_schedule` 'start' | 'end' — Indicates if the product should be billed at the start or the end of the payment interval.
          - `price` object — Similar to `prices`, allow to apply a single fee price more easily.
            - `type` 'fee', required
            - `amount` number, required — Monetary amount. Expressed in currency's smallest unit.
          - `prices` union[] — Prices of the product. If not specified, the matching prices (depending on the currency, interval, etc) of the product defined in the products catalog/plan are used.
            - union
              - …
          - `count` number — Number of product units. Only applies to products of type `flat_fee`, `seat` or `credit`.
          - `unit_name` string — Product name. This will appear on the final invoices. Only applies to products of type `seat` or `usage`.
          - `min_committed_count` number — Minimum of units committed. If usage is less than this number, then this value will be used. Only applies to products of type `usage`.
          - `min_amount` number, nullable — Minimum amount billed. If the final computed amount from the usage for this product is less than this amount, then this value will be used. Only applies to products of type `usage`.
          - `max_amount` number, nullable — Maximum amount billed. If the final computed amount from the usage for this product is greater than this amount, then this value will be used. Only applies to products of type `usage`.
          - `charging_method` 'prorata' | 'pay_in_full' | 'do_not_charge', nullable — Charging method for seat count updates within the current billing period. Only applies to connected seat products. - `prorata`: Price calculated proportionally to time elapsed in the billing period. - `pay_in_full`: Price calculated for the entire billing period. - `do_not_charge`: No charge for the update.
          - `seat_invoicing_schedule` 'immediately' | 'next_invoice' | 'custom', nullable — Policy defining when seat count changes are invoiced. Only applies to connected seat products. - `immediately`: Seat changes are invoiced immediately. - `next_invoice`: Seat changes are invoiced at the next invoice. - `custom`: Seat changes are invoiced on a custom schedule.
          - `metering_interval_type` 'subscription_commitment' | 'payment_interval' | 'full_database' | 'custom' — Indicates on which type of interval the usage should be aggregated. - `subscription_commitment`: For the usage contained within the subscription commitment period. - `payment_interval`: For the usage contained within the payment interval of the product. - `full_database`: For all the usage we ingested for this product, no matter the period. - `custom`: For the usage contained within a custom interval that starts with the phase and renews independently of the billing interval. Requires `metering_interval` to be set. Only applies to products of type `usage`.
          - `metering_interval` object — Custom interval for usage aggregation. Required when `metering_interval_type` is `custom`. The interval starts at the phase start and renews on its own cycle (e.g. `{ period: 'months', count: 3 }` for quarterly metering with monthly billing). Only applies to products of type `usage`.
            - `period` 'days' | 'weeks' | 'months' | 'years', required
            - `count` integer, required
          - `bill_usage_difference` union — Only bill the usage difference comparing to the previous period (i.e. actual amount minus last invoice amount). Doesn't apply to `payment_interval` metering interval type. Only applies to products of type `usage`.
            - boolean
            - 'true' | 'false'
          - `children_usage_aggregation` 'sum' | 'max', nullable — Controls whether a parent organization's metered usage is billed on the combined usage of the parent and its direct children, and how per-member values are combined. - `null`: Organization-based usage is disabled. Only the subscription customer's own usage is billed. - `sum`: The usage values of the parent and each direct child are added together (organization total). - `max`: Only the single highest-consuming member (parent or one direct child) is billed. Only applies to products of type `usage`. Not compatible with BPS prices.
          - `credits_expiration_in_days` number, nullable — Validity in days for credits that will be topped-up automatically. Once the period has passed, they'll expire.
          - `expire_credits_at_end_of_period` union — Automatically set the expiration date to the end of the next period for each topup. Takes priority on `creditsExpirationInDays`
            - boolean
            - 'true' | 'false'
        - `coupons` union[] — Coupons comprising the subscription phase.
          - union
            - object
              - …
            - object
              - …
            - object
              - …
    - object — The configuration of the subscription to transition to
      - `name` string — Subscription custom name.
      - `purchase_order` string — Reference to the purchase order.
      - `invoicing_entity_id` string — ID of the invoicing entity attached to the subscription. If not defined, fallback to customer's invoicing entity.
      - `crm_opportunity_id` string — ID of the related opportunity/deal in the connected CRM.
      - `commitment_interval` object — Deprecated field, please use `contract_terms`.
        - `period` 'days' | 'weeks' | 'months' | 'years', required
        - `count` number, required
      - `renew_for` object — Deprecated field, please use `contract_terms`.
        - `period` 'days' | 'weeks' | 'months' | 'years', required
        - `count` number, required
      - `minimum_invoice_fee` number, nullable — Minimum fee applied to each invoice outside of one time payments.
      - `contract_terms` object — Contract terms linked to the subscription.
        - `starts_at` string, date-time — Start date of the contract. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        - `ends_at` string, date-time — End date of the contract. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        - `duration` object — Interval over which the contract initially spans. Only applies to `duration` end strategy.
          - `period` 'days' | 'weeks' | 'months' | 'years', required
          - `count` integer
        - `renew_automatically` union — Indicates if the contract should be renewed automatically. - `true`: The contract will be renewed automatically. - `false`: The contract will not be renewed automatically.
          - boolean
          - 'true' | 'false'
        - `renew_for_duration` object — Interval over which the contract will be renewed. Only applies if `renew_automatically` is true.
          - `period` 'days' | 'weeks' | 'months' | 'years', required
          - `count` integer
        - `activation_strategy` 'start_date' | 'immediately' | 'manual' | 'quote_signature' | 'checkout', required — Activation strategy of the contract. - `immediately`: The contract will be activated immediately. - `manual`: The contract will be activated when a user manually activates it. - `start_date`: The contract will be activated on a specified date. - `quote_signature`: The contract will be activated when the subscription quote is signed. - `checkout`: The contract will be activated when the subscription checkout is completed.
        - `end_strategy` 'end_date' | 'duration' | 'manual', required — End strategy of contract. - `manual`: The contract ends when a user manually stops it. - `end_date`: The contract ends on a specified date. - `duration`: The contract ends after a specific relative duration, unless `renew_automatically` is true.
      - `starts_at` string, date-time — Applies only if the activation strategy is `start_date`. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
      - `contract_start` string, date-time — Deprecated field, please use `contract_terms`.
      - `contract_end` string, date-time — Deprecated field, please use `contract_terms`.
      - `initial_billing_at` string, date-time — Date when the subscription will start being billed. If not specified, it will correspond to the `starts_at` date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
      - `display_shipping_details` union — Indicates if the shipping details should be displayed on the subscription's invoices.
        - boolean
        - 'true' | 'false'
      - `cancel_at` string, date-time — Subscription cancel date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
      - `cancellation_strategy` 'refund_prorata' | 'refund_custom' | 'charge_prorata' | 'charge_custom' | 'end_of_period' | 'do_nothing' — Strategy used to cancel the subscription. If not specified `do_nothing` is used. - `charge_prorata`: Will charge the customer the unpaid amount for the prorated period up to the end of the current period. - `charge_custom`: Will charge the customer a custom amount. - `refund_prorata`: Will refund to the customer the overpaid subscription amount using prorated calculations on the cancellation date. - `refund_custom`: Will refund to the customer a custom amount. - `end_of_period`: Will cancel the subscription at the end date of the current billing period. - `do_nothing`: Will only cease the subscription without any additional actions.
      - `cancellation_amount` number — Custom amount used when cancelling the subscription. Only applies to the `charge_custom` or the `refund_custom` cancellation strategy.
      - `cancellation_refund_method` 'wallet' | 'original_payment_method' | 'external' — Override the refund destination for credit notes generated by `refund_prorata` / `refund_custom` cancellation strategies. When omitted, falls back to the invoicing entity's `creditNoteWalletRefundEnabled` setting.
      - `properties` object — Key/value pairs to store any metadata useful in your context.
      - `custom_properties` object — A list of key value with the slug of the custom property as the key and the custom property value as value.
      - `tax_only` union — Only tax will be charged on this subscription.
        - boolean
        - 'true' | 'false'
      - `generate_draft_invoices` union — Generate draft invoices for the subscription. Each invoice will need to be reviewed and validated manually before being sent
        - boolean
        - 'true' | 'false'
      - `generate_document` union — Generate non-legal documents instead of invoices.
        - boolean
        - 'true' | 'false'
      - `document_name` string, nullable — If `generate_document` is turned on, allows you to give a name to your document.
      - `add_tax_to_document` union — If `generate_document` is turned on, will add taxes to document.
        - boolean
        - 'true' | 'false'
      - `do_not_charge_subscription` union — Subscription will be invoiced but not charged (invoices/documents will be settled directly).
        - boolean
        - 'true' | 'false'
      - `invoice_custom_note` string, nullable — Default custom note added to invoices generated by the subscription.
      - `invoice_schedule` 'period_start' | 'period_end', nullable — Defines when invoices are generated relative to the billing period. - `period_start`: Invoices are generated at the start of the billing period. - `period_end`: Invoices are generated at the end of the billing period.
      - `plan_id` string — Deprecated field, please use `template_id`.
      - `template_id` string — ID of the template that the subscription is linked to.
      - `template_configuration_id` string — ID of the template configuration that the subscription is linked to.
      - `products` object[] — Products that make up the subscription.
        - `id` string, required — Product ID.
        - `name` string — Product name. This will appear on the final invoices.
        - `description` string — Product description. This will appear on the final invoices.
        - `description_display_interval_dates` boolean — Indicates if the dates of the interval should be automatically added in the product description on the invoices.
        - `payment_interval` union — Interval on which the product is billed. This interval can be different between products and can differ from the subscription commitment interval.
          - object
            - `period` 'once', required
          - object
            - `period` 'days' | 'weeks' | 'months' | 'years', required
            - `count` integer
        - `payment_schedule` 'start' | 'end' — Indicates if the product should be billed at the start or the end of the payment interval.
        - `price` object — Similar to `prices`, allow to apply a single fee price more easily.
          - `type` 'fee', required
          - `amount` number, required — Monetary amount. Expressed in currency's smallest unit.
        - `prices` union[] — Prices of the product. If not specified, the matching prices (depending on the currency, interval, etc) of the product defined in the products catalog/plan are used.
          - union
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object — For seat products only, if you are looking for credits, use a fee price
              - …
        - `count` number — Number of product units. Only applies to products of type `flat_fee`, `seat` or `credit`.
        - `unit_name` string — Product name. This will appear on the final invoices. Only applies to products of type `seat` or `usage`.
        - `min_committed_count` number — Minimum of units committed. If usage is less than this number, then this value will be used. Only applies to products of type `usage`.
        - `min_amount` number, nullable — Minimum amount billed. If the final computed amount from the usage for this product is less than this amount, then this value will be used. Only applies to products of type `usage`.
        - `max_amount` number, nullable — Maximum amount billed. If the final computed amount from the usage for this product is greater than this amount, then this value will be used. Only applies to products of type `usage`.
        - `charging_method` 'prorata' | 'pay_in_full' | 'do_not_charge', nullable — Charging method for seat count updates within the current billing period. Only applies to connected seat products. - `prorata`: Price calculated proportionally to time elapsed in the billing period. - `pay_in_full`: Price calculated for the entire billing period. - `do_not_charge`: No charge for the update.
        - `seat_invoicing_schedule` 'immediately' | 'next_invoice' | 'custom', nullable — Policy defining when seat count changes are invoiced. Only applies to connected seat products. - `immediately`: Seat changes are invoiced immediately. - `next_invoice`: Seat changes are invoiced at the next invoice. - `custom`: Seat changes are invoiced on a custom schedule.
        - `metering_interval_type` 'subscription_commitment' | 'payment_interval' | 'full_database' | 'custom' — Indicates on which type of interval the usage should be aggregated. - `subscription_commitment`: For the usage contained within the subscription commitment period. - `payment_interval`: For the usage contained within the payment interval of the product. - `full_database`: For all the usage we ingested for this product, no matter the period. - `custom`: For the usage contained within a custom interval that starts with the phase and renews independently of the billing interval. Requires `metering_interval` to be set. Only applies to products of type `usage`.
        - `metering_interval` object — Custom interval for usage aggregation. Required when `metering_interval_type` is `custom`. The interval starts at the phase start and renews on its own cycle (e.g. `{ period: 'months', count: 3 }` for quarterly metering with monthly billing). Only applies to products of type `usage`.
          - `period` 'days' | 'weeks' | 'months' | 'years', required
          - `count` integer, required
        - `bill_usage_difference` union — Only bill the usage difference comparing to the previous period (i.e. actual amount minus last invoice amount). Doesn't apply to `payment_interval` metering interval type. Only applies to products of type `usage`.
          - boolean
          - 'true' | 'false'
        - `children_usage_aggregation` 'sum' | 'max', nullable — Controls whether a parent organization's metered usage is billed on the combined usage of the parent and its direct children, and how per-member values are combined. - `null`: Organization-based usage is disabled. Only the subscription customer's own usage is billed. - `sum`: The usage values of the parent and each direct child are added together (organization total). - `max`: Only the single highest-consuming member (parent or one direct child) is billed. Only applies to products of type `usage`. Not compatible with BPS prices.
        - `credits_expiration_in_days` number, nullable — Validity in days for credits that will be topped-up automatically. Once the period has passed, they'll expire.
        - `expire_credits_at_end_of_period` union — Automatically set the expiration date to the end of the next period for each topup. Takes priority on `creditsExpirationInDays`
          - boolean
          - 'true' | 'false'
      - `coupons` union[]
        - union
          - object
            - `id` string, required — Coupon ID.
            - `repeat` 'once' | 'forever' | 'custom' | 'duration', nullable — Coupon frequency. Required for inline coupons. Optional when an existing coupon `id` is provided: if omitted, defaults to the catalog coupon's repeat value. - `once`: Will apply the coupon only to the first one invoice. - `forever`: Will apply the coupon to all invoices. - `custom`: Will apply to coupon until a specified expiration date. - `duration`: Will apply the coupon for a specific duration (e.g., 3 months).
            - `duration_period` 'days' | 'weeks' | 'months' | 'years' — Period of time for which the coupon will be applied. Only applies to the `duration` coupon frequency.
            - `duration_count` number — Number of periods for which the coupon will be applied. Only applies to the `duration` coupon frequency.
            - `expires_at` string, date-time — Coupon expiration date. Only applies to the `custom` coupon frequency. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
            - `apply_at` string, date-time — Coupon first application date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
            - `product_ids` string[] — Product IDs to which the coupon will be applied.
          - object
            - `type` 'amount', required
            - `name` string — Coupon name.
            - `discount_amount` number, required — Coupon discount amount. Expressed in currency's smallest unit.
            - `repeat` 'once' | 'forever' | 'custom' | 'duration', nullable — Coupon frequency. Required for inline coupons. Optional when an existing coupon `id` is provided: if omitted, defaults to the catalog coupon's repeat value. - `once`: Will apply the coupon only to the first one invoice. - `forever`: Will apply the coupon to all invoices. - `custom`: Will apply to coupon until a specified expiration date. - `duration`: Will apply the coupon for a specific duration (e.g., 3 months).
            - `duration_period` 'days' | 'weeks' | 'months' | 'years' — Period of time for which the coupon will be applied. Only applies to the `duration` coupon frequency.
            - `duration_count` number — Number of periods for which the coupon will be applied. Only applies to the `duration` coupon frequency.
            - `expires_at` string, date-time — Coupon expiration date. Only applies to the `custom` coupon frequency. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
            - `apply_at` string, date-time — Coupon first application date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
            - `product_ids` string[] — Product IDs to which the coupon will be applied.
          - object
            - `type` 'percent', required
            - `name` string — Coupon name.
            - `discount_percent` number, required — Coupon discount percentage.
            - `repeat` 'once' | 'forever' | 'custom' | 'duration', nullable — Coupon frequency. Required for inline coupons. Optional when an existing coupon `id` is provided: if omitted, defaults to the catalog coupon's repeat value. - `once`: Will apply the coupon only to the first one invoice. - `forever`: Will apply the coupon to all invoices. - `custom`: Will apply to coupon until a specified expiration date. - `duration`: Will apply the coupon for a specific duration (e.g., 3 months).
            - `duration_period` 'days' | 'weeks' | 'months' | 'years' — Period of time for which the coupon will be applied. Only applies to the `duration` coupon frequency.
            - `duration_count` number — Number of periods for which the coupon will be applied. Only applies to the `duration` coupon frequency.
            - `expires_at` string, date-time — Coupon expiration date. Only applies to the `custom` coupon frequency. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
            - `apply_at` string, date-time — Coupon first application date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
            - `product_ids` string[] — Product IDs to which the coupon will be applied.
      - `trial` object — Create a free trial phase based on the plan configuration. Only applies if a `plan_id` is provided.
        - `end_strategy` 'manual' | 'end_date' | 'duration', required — Defines how the free trial will end.
        - `starts_at` string, date-time — Free trial start date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        - `ends_at` string, date-time — Free trial end date. Only applies if the end strategy is `end_date`. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        - `duration` object
          - `period` 'days' | 'weeks' | 'months' | 'years', required — Free trial duration period. Only applies if the end strategy is `duration`.
          - `count` number, required — Free trial duration count. Only applies if the end strategy is `duration`.

## Response `200`

- object
  - `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)