Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Create subscription payload.
At least a plan_id, a set of products or phases must be specified in addition to the required fields.
ID of the customer.
"cus_QalW2vTAdkR6IY"
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 "checkout"
Subscription custom name.
Reference to the purchase order.
ID of the invoicing entity attached to the subscription.
"ive_jerrb484RHn"
ID of the related opportunity/deal in the connected CRM.
Deprecated field, please use contract_terms.
{ "period": "years", "count": 1 }Deprecated field, please use contract_terms.
true
Deprecated field, please use contract_terms.
{ "period": "years", "count": 1 }Minimum fee applied to each invoice outside of one time payments.
250
Contract terms linked to the subscription.
Deprecated field, please use contract_terms.
"2024-01-15T00:00:00Z"
Deprecated field, please use contract_terms.
"2025-01-15T00:00:00Z"
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 Custom amount used when cancelling the subscription. Only applies to the charge_custom or the refund_custom cancellation strategy.
Key/value pairs to store any metadata useful in your context.
A list of key value with the slug of the custom property as the key and the custom property value as value.
Only tax will be charged on this subscription.
Generate draft invoices for the subscription. Each invoice will need to be reviewed and validated manually before being sent
Generate non-legal documents instead of invoices.
If generate_document is turned on, allows you to give a name to your document.
If generate_document is turned on, will add taxes to document.
Subscription will be invoiced but not charged (invoices/documents will be settled directly).
ID of the plan used to create the subscription.
"plan_zHmjoDee4ZRmQV"
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"
Set the allowed types of payment methods for the customer. Only applies to the new payment method strategy.
1[On demand] Will split the subscription into 2 phases, one will contain 'once' products and the other the recurring ones. Call next-phase endpoint to transition between the 2 phases.
Create a free trial phase based on the plan configuration. Only applies if a plan_id is provided.
Alignment of product billing cycles. Only applies when creating a subscription from a plan.
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 Products that make up the subscription.
Response
The newly created subscription
Subscription ID.
"sub_B6ClkdqNqVNBgY"
Subscription custom name.
"Yearly subscription"
Currency code. See ISO 4217.
EUR, AED, AFN, XCD, ALL, AMD, AOA, ARS, USD, AUD, AWG, AZN, BAM, BBD, BDT, XOF, BGN, BHD, BIF, 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.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, paused, pending, voided "active"
Reference to the purchase order.
ID of the customer.
"cus_QalW2vTAdkR6IY"
ID of the plan used to create the subscription.
"plan_zHmjoDee4ZRmQV"
ID of the invoicing entity attached to the subscription.
"ive_jerrb484RHn"
ID of the checkout session.
ID of the related opportunity/deal in the connected CRM.
ID of the subscription this subscription was transitioned from.
Minimum fee applied to each invoice outside of one time payments.
250
Deprecated field, please use contract_terms.
{ "period": "years", "count": 1 }Deprecated field, please use contract_terms.
true
Deprecated field, please use contract_terms.
{ "period": "years", "count": 1 }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 "checkout"
Deprecated field, please use contract_terms.
"2024-01-15T00:00:00Z"
Deprecated field, please use contract_terms.
"2025-01-15T00:00:00Z"
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 Custom amount used when cancelling the subscription. Only applies to the charge_custom or the refund_custom cancellation strategy.
Reason for the cancellation.
Estimated Annual Recurring Revenue generated by the subscription.
The amount of the next subscription payment. The system will generate an invoice to pay on the next_payment_at.
ID of the current subscription phase.
Key/value pairs to store any metadata useful in your context.
A list of key value with the slug of the custom property as the key and the custom property value as value.
Generate documents instead of invoices for the subscription.
If generate_document is turned on, allows you to give a name to your document.
If generate_document is turned on, will add taxes to document.
Products that make up the subscription.
Coupons to be applied to the prices of subscription products.
Phases of the subscription.
Checkout session of the subscription.
Payment method type used to pay the subscription.
card, apple_pay, google_pay, direct_debit, direct_debit_ach, direct_debit_bacs, stripe_link, transfer, transfer_automated, external Default payment method of the customer. Only applies to card and direct debit. Payment method details used to pay the subscription.
Generate draft invoices for the subscription. Each invoice will need to be reviewed and validated manually before being sent
Contract terms linked to the subscription.