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.

​

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.

​

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.

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

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).

​

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