Skip to main content
Creating subscriptions is a central capability in Hyperline. In this article, we will explore the various options available to assign them to your customers, from simple to more complex needs. Before starting a subscription, you must configure the products you wish to bill and, optionally create plans to streamline the subscription assignment process, using reusable package configurations.
Though products are configured at the account level, you can customize every option at the customer level, allowing you to adjust them according to specific needs on a per-case basis without impacting your overall configuration.

​
Configure a subscription

Configuring a subscription in Hyperline only takes a few clicks. However, we also provide the flexibility to customize subscriptions on a per-customer basis, offering you greater versatility and agility.
1

From a customer page, click on actions then Assign new subscription

You can also create new subscriptions from the subscription list page. In this case, you will have to select the customer.
2

Optionally, select a pre-configured plan

You can start a subscription either from a pre-configured plan or configure your subscription manually from scratch.
3

Select subscription duration

Subscription start
  • In the past, if you want to backport a subscription that has already started but not in Hyperline, or you want to bill a customer in arrears - any past period that’s due will be billed.
  • Immediately, the default value
  • In the future, if you want to schedule a subscription for the future
  • On checkout completion, once the checkout will be completed by your customer
Subscription alignmentSubscriptions follow a predictable renewal pattern based on their start date:
  • If a subscription begins at the standard start of a billing period (e.g., the 1st of the month for monthly plans or the 1st of the year for annual plans), it aligns automatically, and each new period starts on the same fixed date.
  • If a subscription starts on any other day, it renews on the same calendar day in the next period (e.g., a subscription starting on March 15th renews on April 15th for a monthly plan).
4

Manage contract configuration

In the contract configuration, we allow you to configure a contract duration by activating the toggle.
Contract duration replaces the notion of commitment that has been deprecated. More information here
5

Add products to the subscription

When adding products outside of a plan, after selecting the product, you will be presented with the list of prices that are set in your product catalog. It’s divided in a few sections:

Select the price and billing interval for the given product or select "Manual Configuration"

  • Suggested: will list the best pricing according to various parameter of the subscription: The customer’s country, their currency, the commitment duration.
  • Others: will list the rest of the prices available for the product.
  • Manual configuration: If no matches are found or you don’t find the right price, you can select “Manual configuration” and you can get to the next step where you will be able to enter the price and frequency by yourself.
Once the pricing configuration is selected, you can edit the product details. When editing a product configuration, it will not impact your catalog and only have effect on the subscription you’re currently creating. This gives you the flexibility to set customer-specific pricing.
You can adjust the quantity directly from the main subscription view, making it easy to customize a subscription especially when starting from a pre-configured plan.
6

Optionally, add coupons

You also have the ability to assign coupons to your subscription. These coupons can be a fixed amount in the customers’ currency, or a percentage of the product price. They can apply to specific or all products.

You can either create single use coupon to apply on this subscription only, or one that you have previously set up in your catalog

Once you selected a coupon, you will be able to select:
  • The application date: choose wether the coupon will be applied once, forever or for a custom period (referring to the period during which invoices will be generated)
  • The products it will be applied on (at least one product must be selected)
7

Optionally, add a free trial

Adding a free trial allows you to start a subscription without charging the customer until a specified period has passed. In Hyperline, a free trial creates a new phase that duplicates the first phase, but with all products set to free.
To add a free trial, the first phase must include at least one product.
The free trial is set to 14 days by default. It can be ended After a custom duration like 14 days or 1 month, at a fixed date or with a manual end. The free trial can be terminated earlier on with mark phase as finished.
The free trial details will appear on the checkout page if the subscription is configured to start after checkout completion.
8

Advanced settings

  • Initial billing date
The initial billing date is when the first invoice is sent. It defaults to the subscription’s start date, as set in the subscription duration selector. If the subscription starts on a specific date, theÒ billing date can be set on a custom day (that is always after the subscription start date).
  • Align billing period to the first day of the next cycle
Toggling the option on will make sure that the next billing period is aligned on the first day of the next billing cycle. You can configure this option to be toggled on by default under Settings > Subscriptions.For example, the subscription will charge the first billing period from the start date (e.g., January 14, 2025) until the end of the current cycle (e.g., January 31, 2025, when the product is billed every month). From the next cycle onward, billing will follow the regular interval (e.g., monthly, from February 1, 2025, to February 28, 2025), ensuring alignment with standard billing schedule.
9

Manage invoicing settings

Purchase orderAdd a text element that will be present on the header of every invoice emitted by this subscriptionGenerate draft invoicesThe draft invoices feature allows you to review an invoice before it’s sent. It’s handy if you have to double-check what’s sent to your customer, or when you’re first trying out the platform. When an invoice is generated, it will be set as a draft that you can edit, finalize and then send to your customer.Generate documents instead of invoicesWhen Hyperline generates documents instead of invoices,the documents have no legal value compared to invoices and can be used for reporting. You can chose to add VAT to the document or not and set a custom name for the document.Do not charge subscriptionThe invoices will be created and the invoice will be marked as paid, however, the platform won’t charge for the invoices. It’s handy for adding subscriptions to your reporting when payment is handled elsewhere.

​
Subscription payment

After clicking on the next button Payment settings, you’ll need to configure how you want the subscription to start and your customer to pay it. You can also configure invoicing options as an optional step.

​
Payment methods

On this section, you are shown the default payment method (the one that will be used for charging the invoices), and the allowed payment methods (the ones the customer can add during checkout and on its portal). You can edit the customer’s default payment method and toggle on or off the allowed ones. These changes will be applied on the customer level.

​
Checkout session

Hyperline provides a hosted checkout page for your customers, allowing them to enter their billing details (contact information, address) and add the payment method they wish to use for recurring subscription payments. This page is for single use and is provided at the beginning of the subscription process to allow your customer to complete the act of subscribing to your service.
The use of this page is optional, and can be disabled by toggling off Generate checkout session in the global settings under the Subcriptions section.
Additionally, we provide you a way to add an email address so Hyperline can automatically send the related checkout page link to your customer, without any action from your side.

​
Activation

The subscription activation is now managed within the previous step, now being aligned with the subscription start strategy (quote signature, checkout completion, manually or at a said date).

​
Assign the subscription

When everything is set and ready to go, you can click on Assign subscription. If the customer is going to be charged immediately, you will be reminded with a message that will prevent you from charging unintentionally.

​
Using the API

If you want a deeper technical integration to start subscriptions with no manual action in the product you can use the create subscription endpoint. 
POST /v2/subscriptions
Additonnaly, you can retrieve the subscription’s details using the get subscription endpoint, or list all of them using the get subscriptions endpoint.

​
Create a subscription from a plan

In this example, we create a new subscription from the plan plan_zHmjoDea4ZRmQV for the customer cus_3PYD5R2q5NFK5E, with a starting date on December 12, 2023 and activated by the customer through a generated checkout session sent by email. 
curl --request POST \
  --url https://api.hyperline.co/v2/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer_id": "cus_3PYD5R2q5NFK5E",
    "plan_id": "plan_zHmjoDea4ZRmQV",
    "starts_at": "2023-12-20T00:00:00Z",
    "activation_strategy": "checkout",
    "payment_method_strategy": "current",
    "checkout_session": {
      "send_to": { "email": "josh@acme.com" },
    }
  }'

​
Create a subscription from a list of products

In this example, we create a new subscription with two products paid every month for the customer cus_3PYD5R2q5NFK5E, with a starting date on December 12, 2023 and activated automatically at the start date. The product prices will be automatically determined based on the prices configured in the product catalog for the corresponding currency, interval, etc. 
curl --request POST \
  --url https://api.hyperline.co/v2/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer_id": "cus_3PYD5R2q5NFK5E",
    "starts_at": "2023-12-20T00:00:00Z",
    "activation_strategy": "start_date",
    "payment_method_strategy": "current",
    "products": [
      {
        "id": "itm_4vea8Gj0a5HZr9",
        "payment_interval": { "period": "months" },
      },
      {
        "id": "itm_vBBCZSTR6NzzuL",
        "payment_interval": { "period": "months" },
        "count": 2,
      },
    ]
  }'
Here, product itm_4vea8Gj0a5HZr9 is a fee product and itm_vBBCZSTR6NzzuL a seat one with 2 items applied.

​
Override prices

When creating a subscription, you can override the price for a specific product with a custom amount. Note that this operation is only allowed for flat_fee products. If we take back our previous example and adjust it: 
curl --request POST \
  --url https://api.hyperline.co/v2/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer_id": "cus_3PYD5R2q5NFK5E",
    "starts_at": "2023-12-20T00:00:00Z",
    "activation_strategy": "start_date",
    "payment_method_strategy": "current",
    "products": [
      {
        "id": "itm_4vea8Gj0a5HZr9", # flat_fee product
        "payment_interval": { "period": "months" },
        "price": { type: "fee", amount: 1234 }, # override
      },
      {
        "id": "itm_vBBCZSTR6NzzuL",
        "payment_interval": { "period": "months" },
        "count": 2,
      },
    ]
  }'
⌘I