Create subscription
Create a new subscription from a plan or manually with products.
Authorizations
Body
Create subscription payload.
At least a template_id, a template_configuration_id, a set of products, or phases must be specified in addition to the required fields.
- Without phases
- With phases
- From template
If a template_id or a template_configuration_id is specified, the subscription will be created from scratch, and the template will only be referenced for reporting purposes.
Use From template option to create a subscription from a template.
Strategy used to activate the subscription.
start_date: The subscription will become active on the specified start date. If the start date is in the past, it will be activated immediately.manually: The subscription requires activation through a manual action.checkout: The subscription will be activated once the checkout is completed, but only if the start date is in the past. Otherwise, activation will occur later on the specified start date.quote: The subscription will be activated depending on the configuration and the signature of the related quote.
start_date, manually, checkout "start_date"
Applies only if the activation strategy is start_date. UTC date time string in the ISO 8601 format.
"2024-12-20T16:04:11Z"
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.
"2024-12-20T16:04:11Z"
Subscription cancel date. UTC date time string in the ISO 8601 format.
"2024-12-20T16:04:11Z"
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.
refund_prorata, refund_custom, charge_prorata, charge_custom, end_of_period, do_nothing 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.
wallet, original_payment_method, external Payment method strategy used to bill the subscription. By default, the current payment method of the customer will be used.
new: Ask the customer for a new payment method. The customer can fill in their payment method either on the subscription's checkout session or on their portal page.current: Use the current default payment method of the customer.external: Manage the payments of the subscription outside of Hyperline.
current, external, new "current"
Alignment of product billing cycles. Only applies when creating a subscription from a plan. If omitted, the billing cycles alignment configured in the account subscription settings applies.
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.
calendar_period, anniversary Response
The newly created subscription
Currency code. See ISO 4217.
EUR, AED, AFN, XCD, ALL, AMD, AOA, ARS, USD, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, XOF, BMD, BND, BOB, BRL, BSD, BTN, NOK, BWP, BYR, BZD, CAD, CDF, XAF, CHF, NZD, CLP, CNY, COP, CRC, CUP, CVE, ANG, CZK, DJF, DKK, DOP, DZD, EGP, MAD, ERN, ETB, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MYR, MZN, NAD, XPF, NGN, NIO, NPR, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, SSP, STD, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, UYU, UZS, VEF, VND, VUV, WST, YER, ZAR, ZMW, ZWL "EUR"
Subscription status.
draft: The subscription is being created, this status is only used in the subscription assignation flow of the UI version of Hyperline.pending: The subscription has been created and won't be charged until it is activated.active: The subscription is running and will be invoiced at the next payment date.paused: The subscription's payment collection is paused.cancelled: The subscription has been canceled from an active state.voided: The subscription has been voided directly from the pending state.archived: The subscription is a previous version kept after an update.errored: We attempted 4 times (3 retries) and failed to charge a subscription's invoice, see Handling payment errors. We consider the subscription as inactive (as the customer failed to pay you) meaning that we won't invoice the customer in the future nor collect payment. You can choose to reactivate it manually.
active, cancelled, draft, errored, archived, paused, pending, voided "active"
Strategy used to activate the subscription.
start_date: The subscription will become active on the specified start date. If the start date is in the past, it will be activated immediately.manually: The subscription requires activation through a manual action.checkout: The subscription will be activated once the checkout is completed, but only if the start date is in the past. Otherwise, activation will occur later on the specified start date.quote: The subscription will be activated depending on the configuration and the signature of the related quote.
start_date, manually, checkout, quote, contract_start_date "start_date"
Applies only if the activation strategy is start_date. UTC date time string in the ISO 8601 format.
"2024-12-20T16:04:11Z"
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.
"2024-12-20T16:04:11Z"
Date when the subscription was paused. Only applies to paused status. UTC date time string in the ISO 8601 format.
"2024-12-20T16:04:11Z"
Date when the subscription will be automatically reactivated (paused status) or reinstated (cancelled status). UTC date time string in the ISO 8601 format.
"2024-12-20T16:04:11Z"
Subscription cancel date. UTC date time string in the ISO 8601 format.
"2024-12-20T16:04:11Z"
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.
refund_prorata, refund_custom, charge_prorata, charge_custom, end_of_period, do_nothing Origin of the cancellation.
portal: customer cancelled themselves from the hosted customer portal.app: admin cancelled from the Hyperline dashboard.api: cancelled programmatically through the public API.system: cancelled by an automated internal process.
portal, app, api, system Start date of the current billing period. UTC date time string in the ISO 8601 format.
"2024-12-20T16:04:11Z"
End date of the current billing period. UTC date time string in the ISO 8601 format.
"2024-12-20T16:04:11Z"
Date on which the next subscription payment will occur. UTC date time string in the ISO 8601 format.
"2024-12-20T16:04:11Z"
Next subscription commitment renewal date. UTC date time string in the ISO 8601 format.
"2024-12-20T16:04:11Z"
Subscription creation date. UTC date time string in the ISO 8601 format.
"2024-10-12T07:00:01.860Z"
Subscription last edition date. UTC date time string in the ISO 8601 format.
"2024-10-12T07:00:01.860Z"

