Skip to main content
POST
/
v2
/
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_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

​
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

200 - application/json
​
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 | 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,
cancelled
​
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,
next_renewal
​
billing_cycle_transition_method
enum<string> | null
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.

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