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 plan or from scratch with the products from your catalog.

3

Select the duration of the subscription

Subscription start

  • In the past, if you want to backport a subscription that has already started but not in Hyperline yet
  • Immediately, the default value
  • In the future, if you want to schedule a subscription for the future.
  • At checkout completion, when the checkout will be completed by your customer.

Subscription alignment

If the subscription starts on the first day of the payment interval, it will be automatically aligned to finish at the end of the payment interval.

Example: my subscription is billed monthly. If my subscription starts on March 1st, the billing period will finish on March 31st ; the next one will start on April 1st, and end on April 30th, taking into account the number of days in the month.

If the subscription starts on any other day of the payment interval, the next payment date will be on the anniversary date.

Example: my subscription is billed annually. If my subscription starts on March 14th, 2024, the billing period will finish on March 14th, 2025 and so on.

Subscription end

The subscription end date will automatically cancel the subscription at the set date without any additional charge or refund. There are three end strategies available:

  • After a duration
  • End at a fixed date
  • Keep on running forever

Initial billing date

The initial billing date defines when the first invoices will be emmitted. By default, it is the same as the subscription start date, wether it is a set date, starting after the checkout is completed or when manually activated. When the subscription starts at a set date, it can be set at any date after that subscription start date.

When the subscription start date is set in the past and the initial billing is set at the same date in the past, all invoices due from the set date until the subscription activation will be generated and charged to the customer.

4

Manage contract settings

In the contract 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, when you override the price for a given product, it will not impact your product catalog, it will only have an effect on the subscription you are editing.

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

6

Add products outside of a plan

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.

You can always get back to the pricing selection by clicking on "Change pricing" or override the price that has been prefilled

7

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.

8

Manage invoicing settings

Purchase order

Add a text element that will be present on the header of every invoice emitted by this subscription

Generate draft invoices

The 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 invoices

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

​
Subscription payment

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.

​
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 the Generate checkout session option in the global settings, on the subscriptions page.

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

Subscription activation is now managed in the previous step. It is linked to the subscription duration start date and can be at a said date, manually or after checkout completion.

​
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

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

Was this page helpful?

How do subscriptions work?Metering options