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 some plans to streamline the subscription assignment process, using reusable package configurations.

​

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, click on Actions then Assign new subscription

2

Optionally, select a pre-configured plan

You can start a subscription either from a pre-configured plan and from scratch with a set of products.

3

Select the duration of the subscription

You can start a subscription:

• In the past, if you want to backport a subscription that has already started but not in Hyperline yet for example - but be careful as we will bill any past period that’s due.
• Immediately, the default value
• In the future, if you want to schedule a subscription for the future

Subscription alignment

You can choose to align a subscription with a calendar month or year.

The default option is to bill on the anniversary date of the subscription. If you chose to align to the month, the subscription will start at the beginning of the month and will be billed within the month.

Example: For the month of February, the invoicing period will be from the 1st to the 28th or 29th instead of from the 1st of February to the 1st of March.

4

Optionally, configure a commitment or a trial period

In the advanced configuration, we allow you to configure a commitment period during which you want your client to commit, and/or a date until which the subscription is in trial period.

If a trial date is configured, the first payment of the subscription can be delayed until the end of this period. This allows you, for example, to enable experimentation time of your tool to your customers, giving them the option to cancel the subscription if they are not satisfied with the service before paying something.

If a plan is selected, these configurations are automatically prefilled.

5

Adjust the products

Select, remove, adjust the products either prefilled from a selected plan or from scratch. Additional settings are available depending on the type of product (fee, seat, usage).

At this step, you can override the price for each product previously defined on the catalog only for this customer’s subscription without impacting one of the shared catalog.

This gives you high flexibility to use different prices per customer while still defining a base price for your offer.

6

Optionally, assign coupons

You also have the ability to assign coupons to your subscription.

That’s it! Your subscription is ready to be started.

​

Start a subscription

After clicking on the next button Payment setting, 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.

​

Advanced settings

​

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.

Additionally, we provide you a way to add an email address so Hyperline can automatically send the related checkout page link directly to your customer, without any action from you.

​

Invoicing options

These settings allow you to manage how invoicing works for the subscription you’re assigning

Generate draft invoices

The draft invoices feature allows you to review an invoice before it’s sent. It’s handy if you have it as part of your process to double-check what’s sent to the final client, or when you’re first trying out the platform. When an invoice is due to be paid, it will be set as a draft that you can finalize so that it’s sent.

Do not charge subscription

The 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 reporting and adding subscriptions to your reporting when payment is handled elsewhere.

Generate documents instead of invoices

When this option is selected, Hyperline will generate documents instead of invoices. The difference is that the documents have no legal value 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.

​

Payment

Three options are offered for your customer to pay.

• using the current payment method, which is only available if the customer already has a saved payment method (i.e. the customer has used a checkout page in the past or you have assigned them a default payment method).
• using a new payment method, which will reset the customer’s default payment method and update their allowed payment methods with the selected ones. If the “Generate checkout session” option is selected, the session will be limited to only the chosen payment methods. If the creation of a checkout session is disabled, the customer will still be able to add/update their payment method on their portal page, also limited to only the chosen payment methods.
• using an external payment method, which will disable all payment-related capabilities in Hyperline and needs to be managed on your side. This means payment collection, the payment method section on checkout and portal pages will be disabled.

​

Activation

Three options are also offered to activate the subscription.

• Immediately or Starting on …, the subscription will start either immediately or on the specified starting date.
• Manually later, the subscription must be activated manually on the customer page.
• After checkout, this option is only available if you decide to generate a checkout session. The subscription will be automatically activated if the starting date has passed when the customer completes the checkout session. If the starting date is later than the checkout completion date, the subscription will be automatically activated on the starting date.

When activated and started, the first invoice will be automatically sent to the customer depending on the products charged or that need to be paid (more details about invoice emails).

​

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,
      },
    ]
  }'