Create subscription transition

curl --request POST \
  --url https://api.hyperline.co/v2/subscriptions/transitions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "source_subscription_id": "<string>",
  "application_schedule": "scheduled",
  "target_subscription": {
    "name": "<string>",
    "purchase_order": "<string>",
    "invoicing_entity_id": "ive_jerrb484RHn",
    "crm_opportunity_id": "<string>",
    "commitment_interval": {
      "period": "years",
      "count": 1
    },
    "renew_automatically": true,
    "renew_for": {
      "period": "years",
      "count": 1
    },
    "minimum_invoice_fee": 250,
    "contract_terms": {
      "activation_strategy": "start_date",
      "end_strategy": "duration",
      "starts_at": "2024-12-20T16:04:11Z",
      "ends_at": "2024-12-20T16:04:11Z",
      "duration": {
        "count": 6,
        "period": "months"
      },
      "renew_automatically": true,
      "renew_for_duration": {
        "count": 1,
        "period": "years"
      }
    },
    "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",
    "display_shipping_details": true,
    "cancel_at": "2024-12-20T16:04:11Z",
    "cancellation_strategy": "refund_prorata",
    "cancellation_amount": 123,
    "properties": {},
    "custom_properties": {},
    "tax_only": true,
    "generate_draft_invoices": true,
    "generate_document": true,
    "document_name": "<string>",
    "add_tax_to_document": true,
    "do_not_charge_subscription": true,
    "plan_id": "plan_zHmjoDee4ZRmQV",
    "template_id": "subt_7gdusOkqr5L0B8",
    "template_configuration_id": "subtc_7mHWOlPStUogvp",
    "products": [
      {
        "id": "itm_FJKlqUb8COXw55",
        "name": "Product name",
        "description": "A description of the product.",
        "description_display_interval_dates": false,
        "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": 21,
            "to": null,
            "amount": 150,
            "unit_count": 1,
            "on_tier_incomplete": null
          }
        ],
        "count": 2,
        "unit_name": "user",
        "min_committed_count": 2,
        "min_amount": 123,
        "max_amount": 123,
        "metering_interval_type": "subscription_commitment",
        "bill_usage_difference": false,
        "credits_expiration_in_days": 123,
        "expire_credits_at_end_of_period": false
      }
    ],
    "coupons": [
      {
        "id": "<string>",
        "repeat": "once",
        "duration_period": "days",
        "duration_count": 123,
        "expires_at": "2024-12-20T16:04:11Z",
        "apply_at": "2024-12-20T16:04:11Z",
        "product_ids": [
          "<string>"
        ]
      }
    ],
    "trial": {
      "end_strategy": "manual",
      "starts_at": "2024-12-20T16:04:11Z",
      "ends_at": "2024-12-20T16:04:11Z",
      "duration": {
        "period": "days",
        "count": 2
      }
    }
  },
  "name": "<string>",
  "calculation_method": "do_not_charge",
  "billing_cycle_transition_method": "keep_current_billing_cycle",
  "transition_date": "2024-12-20T16:04:11Z"
}
'

{
  "id": "<string>",
  "customer_id": "<string>",
  "base_subscription_id": "<string>",
  "source_subscription_id": "<string>",
  "target_subscription_id": "<string>",
  "status": "scheduled",
  "transitioned_at": "2023-12-25",
  "name": "<string>",
  "transition_date": "2023-12-25",
  "application_schedule": "immediately",
  "billing_cycle_transition_method": "keep_current_billing_cycle",
  "calculation_method": "do_not_charge"
}

POST

subscriptions

transitions

Create subscription transition

curl --request POST \
  --url https://api.hyperline.co/v2/subscriptions/transitions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "source_subscription_id": "<string>",
  "application_schedule": "scheduled",
  "target_subscription": {
    "name": "<string>",
    "purchase_order": "<string>",
    "invoicing_entity_id": "ive_jerrb484RHn",
    "crm_opportunity_id": "<string>",
    "commitment_interval": {
      "period": "years",
      "count": 1
    },
    "renew_automatically": true,
    "renew_for": {
      "period": "years",
      "count": 1
    },
    "minimum_invoice_fee": 250,
    "contract_terms": {
      "activation_strategy": "start_date",
      "end_strategy": "duration",
      "starts_at": "2024-12-20T16:04:11Z",
      "ends_at": "2024-12-20T16:04:11Z",
      "duration": {
        "count": 6,
        "period": "months"
      },
      "renew_automatically": true,
      "renew_for_duration": {
        "count": 1,
        "period": "years"
      }
    },
    "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",
    "display_shipping_details": true,
    "cancel_at": "2024-12-20T16:04:11Z",
    "cancellation_strategy": "refund_prorata",
    "cancellation_amount": 123,
    "properties": {},
    "custom_properties": {},
    "tax_only": true,
    "generate_draft_invoices": true,
    "generate_document": true,
    "document_name": "<string>",
    "add_tax_to_document": true,
    "do_not_charge_subscription": true,
    "plan_id": "plan_zHmjoDee4ZRmQV",
    "template_id": "subt_7gdusOkqr5L0B8",
    "template_configuration_id": "subtc_7mHWOlPStUogvp",
    "products": [
      {
        "id": "itm_FJKlqUb8COXw55",
        "name": "Product name",
        "description": "A description of the product.",
        "description_display_interval_dates": false,
        "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": 21,
            "to": null,
            "amount": 150,
            "unit_count": 1,
            "on_tier_incomplete": null
          }
        ],
        "count": 2,
        "unit_name": "user",
        "min_committed_count": 2,
        "min_amount": 123,
        "max_amount": 123,
        "metering_interval_type": "subscription_commitment",
        "bill_usage_difference": false,
        "credits_expiration_in_days": 123,
        "expire_credits_at_end_of_period": false
      }
    ],
    "coupons": [
      {
        "id": "<string>",
        "repeat": "once",
        "duration_period": "days",
        "duration_count": 123,
        "expires_at": "2024-12-20T16:04:11Z",
        "apply_at": "2024-12-20T16:04:11Z",
        "product_ids": [
          "<string>"
        ]
      }
    ],
    "trial": {
      "end_strategy": "manual",
      "starts_at": "2024-12-20T16:04:11Z",
      "ends_at": "2024-12-20T16:04:11Z",
      "duration": {
        "period": "days",
        "count": 2
      }
    }
  },
  "name": "<string>",
  "calculation_method": "do_not_charge",
  "billing_cycle_transition_method": "keep_current_billing_cycle",
  "transition_date": "2024-12-20T16:04:11Z"
}
'

{
  "id": "<string>",
  "customer_id": "<string>",
  "base_subscription_id": "<string>",
  "source_subscription_id": "<string>",
  "target_subscription_id": "<string>",
  "status": "scheduled",
  "transitioned_at": "2023-12-25",
  "name": "<string>",
  "transition_date": "2023-12-25",
  "application_schedule": "immediately",
  "billing_cycle_transition_method": "keep_current_billing_cycle",
  "calculation_method": "do_not_charge"
}

Authorizations

Authorization

string

header

required

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

Body

application/json

source_subscription_id

string

required

The ID of the subscription to transition from

application_schedule

enum<string>

required

Whether the transition should be applied 'immediately' or 'scheduled' for a future date.

Available options:

scheduled,

immediately

target_subscription

Without phases · object

required

The configuration of the subscription to transition to

Without phases
With phases

Show child attributes

target_subscription.name

string

Subscription custom name.

target_subscription.purchase_order

string

Reference to the purchase order.

target_subscription.invoicing_entity_id

string

ID of the invoicing entity attached to the subscription.

Example:

"ive_jerrb484RHn"

target_subscription.crm_opportunity_id

string

ID of the related opportunity/deal in the connected CRM.

target_subscription.commitment_interval

object

deprecated

Deprecated field, please use contract_terms.

Show child attributes

target_subscription.commitment_interval.period

enum<string>

required

Available options:

days,

weeks,

months,

years

target_subscription.commitment_interval.count

number

required

Required range: x >= 1

Example:

{ "period": "years", "count": 1 }

target_subscription.renew_automatically

default:true

deprecated

Deprecated field, please use contract_terms.

Example:

true

target_subscription.renew_for

object

deprecated

Deprecated field, please use contract_terms.

Show child attributes

target_subscription.renew_for.period

enum<string>

required

Available options:

days,

weeks,

months,

years

target_subscription.renew_for.count

number

required

Example:

{ "period": "years", "count": 1 }

target_subscription.minimum_invoice_fee

number | null

Minimum fee applied to each invoice outside of one time payments.

Example:

250

target_subscription.contract_terms

object

Contract terms linked to the subscription.

Show child attributes

target_subscription.contract_terms.activation_strategy

enum<string>

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.

Available options:

start_date,

immediately,

manual,

quote_signature,

checkout

Example:

"start_date"

target_subscription.contract_terms.end_strategy

enum<string>

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.

Available options:

end_date,

duration,

manual

Example:

"duration"

target_subscription.contract_terms.starts_at

string<date-time>

Start date of the contract. UTC date time string in the ISO 8601 format.

Example:

"2024-12-20T16:04:11Z"

target_subscription.contract_terms.ends_at

string<date-time>

End date of the contract. UTC date time string in the ISO 8601 format.

Example:

"2024-12-20T16:04:11Z"

target_subscription.contract_terms.duration

object

Interval over which the contract initially spans. Only applies to duration end strategy.

Show child attributes

target_subscription.contract_terms.duration.period

enum<string>

required

Available options:

days,

weeks,

months,

years

target_subscription.contract_terms.duration.count

integer

default:1

Required range: x >= 1

Example:

{ "count": 6, "period": "months" }

target_subscription.contract_terms.renew_automatically

Indicates if the contract should be renewed automatically.

true: The contract will be renewed automatically.
false: The contract will not be renewed automatically.

Example:

true

target_subscription.contract_terms.renew_for_duration

object

Interval over which the contract will be renewed. Only applies if renew_automatically is true.

Show child attributes

target_subscription.contract_terms.renew_for_duration.period

enum<string>

required

Available options:

days,

weeks,

months,

years

target_subscription.contract_terms.renew_for_duration.count

integer

default:1

Required range: x >= 1

Example:

{ "count": 1, "period": "years" }

target_subscription.starts_at

string<date-time>

Applies only if the activation strategy is start_date. UTC date time string in the ISO 8601 format.

Example:

"2024-12-20T16:04:11Z"

target_subscription.contract_start

string<date-time>

deprecated

Deprecated field, please use contract_terms.

Example:

"2024-01-15T00:00:00Z"

target_subscription.contract_end

string<date-time>

deprecated

Deprecated field, please use contract_terms.

Example:

"2025-01-15T00:00:00Z"

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

Example:

"2024-12-20T16:04:11Z"

target_subscription.display_shipping_details

Indicates if the shipping details should be displayed on the subscription's invoices.

target_subscription.cancel_at

string<date-time>

Subscription cancel date. UTC date time string in the ISO 8601 format.

Example:

"2024-12-20T16:04:11Z"

target_subscription.cancellation_strategy

enum<string>

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.

Available options:

refund_prorata,

refund_custom,

charge_prorata,

charge_custom,

end_of_period,

do_nothing

target_subscription.cancellation_amount

number

Custom amount used when cancelling the subscription. Only applies to the charge_custom or the refund_custom cancellation strategy.

target_subscription.properties

object

Key/value pairs to store any metadata useful in your context.

Show child attributes

target_subscription.properties.{key}

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

Show child attributes

target_subscription.custom_properties.{key}

target_subscription.tax_only

Only tax will be charged on this subscription.

target_subscription.generate_draft_invoices

Generate draft invoices for the subscription. Each invoice will need to be reviewed and validated manually before being sent

target_subscription.generate_document

Generate non-legal documents instead of invoices.

target_subscription.document_name

string | null

If generate_document is turned on, allows you to give a name to your document.

target_subscription.add_tax_to_document

If generate_document is turned on, will add taxes to document.

target_subscription.do_not_charge_subscription

Subscription will be invoiced but not charged (invoices/documents will be settled directly).

target_subscription.plan_id

string

deprecated

ID of the plan that the subscription is linked to.

Example:

"plan_zHmjoDee4ZRmQV"

target_subscription.template_id

string

ID of the template that the subscription is linked to.

Example:

"subt_7gdusOkqr5L0B8"

target_subscription.template_configuration_id

string

ID of the template configuration that the subscription is linked to.

Example:

"subtc_7mHWOlPStUogvp"

target_subscription.products

object[]

Products that make up the subscription.

Show child attributes

target_subscription.products.id

string

required

Product ID.

Example:

"itm_FJKlqUb8COXw55"

target_subscription.products.name

string

Product name. This will appear on the final invoices.

Example:

"Product name"

target_subscription.products.description

string

Product description. This will appear on the final invoices.

Example:

"A description of the product."

target_subscription.products.description_display_interval_dates

boolean

default:false

Indicates if the dates of the interval should be automatically added in the product description on the invoices.

target_subscription.products.payment_interval

Once · object

Interval on which the product is billed. This interval can be different between products and can differ from the subscription commitment interval.

Once
Period

Show child attributes

target_subscription.products.payment_interval.period

enum<string>

required

Available options:

once

Example:

{ "period": "once" }

target_subscription.products.payment_schedule

enum<string>

Indicates if the product should be billed at the start or the end of the payment interval.

Available options:

start,

end

Example:

"start"

target_subscription.products.price

object

Similar to prices, allow to apply a single fee price more easily.

Show child attributes

target_subscription.products.price.type

enum<string>

required

Available options:

fee

target_subscription.products.price.amount

number

required

Monetary amount. Expressed in currency's smallest unit.

Example:

{ "type": "fee", "amount": 200 }

target_subscription.products.prices

(Fee price · object | Volume price · object | Packaged price · object | Bulk price · object | BPS price · object)[]

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.

Fee price
Volume price
Packaged price
Bulk price
BPS price

Show child attributes

target_subscription.products.prices.type

enum<string>

required

Available options:

fee

target_subscription.products.prices.amount

number

required

Monetary amount. Expressed in currency's smallest unit.

Example:

[
  {
    "type": "volume",
    "from": 0,
    "to": 20,
    "amount": 200,
    "unit_count": 1,
    "on_tier_incomplete": null
  },
  {
    "type": "volume",
    "from": 21,
    "to": null,
    "amount": 150,
    "unit_count": 1,
    "on_tier_incomplete": null
  }
]

target_subscription.products.count

number

Number of product units. Only applies to products of type flat_fee, seat or credit.

Required range: x >= 1

Example:

2

target_subscription.products.unit_name

string

Product name. This will appear on the final invoices. Only applies to products of type seat or usage.

Example:

"user"

target_subscription.products.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.

Required range: x >= 1

target_subscription.products.min_amount

number

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.

target_subscription.products.max_amount

number

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.

target_subscription.products.metering_interval_type

enum<string>

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. Only applies to products of type usage.

Available options:

subscription_commitment,

payment_interval,

full_database

target_subscription.products.bill_usage_difference

default:false

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.

target_subscription.products.credits_expiration_in_days

number | null

Validity in days for credits that will be topped-up automatically. Once the period has passed, they'll expire.

target_subscription.products.expire_credits_at_end_of_period

default:false

Automatically set the expiration date to the end of the next period for each topup. Takes priority on creditsExpirationInDays

target_subscription.coupons

(Existing coupon · object | Coupon amount · object | Coupon percent · object)[]

Existing coupon
Coupon amount
Coupon percent

Show child attributes

target_subscription.coupons.id

string

required

Coupon ID.

target_subscription.coupons.repeat

enum<string>

required

Coupon frequency.

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

Available options:

once,

forever,

custom,

duration

target_subscription.coupons.duration_period

enum<string>

Period of time for which the coupon will be applied. Only applies to the duration coupon frequency.

Available options:

days,

weeks,

months,

years

target_subscription.coupons.duration_count

number

Number of periods for which the coupon will be applied. Only applies to the duration coupon frequency.

target_subscription.coupons.expires_at

string<date-time>

Coupon expiration date. Only applies to the custom coupon frequency. UTC date time string in the ISO 8601 format.

Example:

"2024-12-20T16:04:11Z"

target_subscription.coupons.apply_at

string<date-time>

Coupon first application date. UTC date time string in the ISO 8601 format.

Example:

"2024-12-20T16:04:11Z"

target_subscription.coupons.product_ids

string[]

Product IDs to which the coupon will be applied.

target_subscription.trial

object

Create a free trial phase based on the plan configuration. Only applies if a plan_id is provided.

Show child attributes

target_subscription.trial.end_strategy

enum<string>

required

Defines how the free trial will end.

Available options:

manual,

end_date,

duration

target_subscription.trial.starts_at

string<date-time>

Free trial start date. UTC date time string in the ISO 8601 format.

Example:

"2024-12-20T16:04:11Z"

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

Example:

"2024-12-20T16:04:11Z"

target_subscription.trial.duration

object

Show child attributes

target_subscription.trial.duration.period

enum<string>

required

Free trial duration period. Only applies if the end strategy is duration.

Available options:

days,

weeks,

months,

years

target_subscription.trial.duration.count

number

required

Free trial duration count. Only applies if the end strategy is duration.

Required range: x >= 1

name

string

An optional name for the transition

calculation_method

enum<string>

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.

Available options:

do_not_charge,

pro_rata

billing_cycle_transition_method

enum<string>

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.

Available options:

keep_current_billing_cycle,

align_to_new_billing_cycle

transition_date

string<date-time>

The date at which the transition should occur. Only applicable if the application schedule is 'scheduled'. UTC date time string in the ISO 8601 format.

Example:

"2024-12-20T16:04:11Z"

Response

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 | null

required

The ID of the subscription to transition to

status

enum<string>

required

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

Available options:

scheduled,

completed,

failed,

draft

transitioned_at

string<date> | null

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.

name

string | null

required

An optional name for the transition

transition_date

string<date> | null

required

The date at which the transition should occur. Only applicable if the application schedule is 'scheduled'. UTC date time string in the ISO 8601 format.

application_schedule

enum<string>

required

Whether the transition should be applied 'immediately' or 'scheduled' for a future date.

Available options:

immediately,

scheduled

billing_cycle_transition_method

enum<string> | null

required

Available options:

keep_current_billing_cycle,

align_to_new_billing_cycle

calculation_method

enum<string> | null

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.

Available options:

do_not_charge,

pro_rata

Create subscription Update subscription

⌘I

API documentation

Integrations

Analytics

Bank Accounts

Billable events

Companies

Coupons

Coupons > Promotion codes

Custom properties

Customers

Customers > Credits

Customers > Payment methods

Exports

Files

Integrations

Invoices

Invoices > Transactions

Invoicing entities

OAuth2

Organisations

Payments

Plans

Price configurations

Products

Quotes

Subscriptions

Subscriptions > Templates

Taxes

Third-party apps

Wallets

Webhooks

Create subscription transition

Authorizations

Body

Response