In this guide, we will see how to implement Hyperline subscription in the context of a self-served product.

​
Context

You have a pricing page on your marketing website and want your customer to subscribe when clicking on an offer.

​
Prerequisites

  1. Create an Hyperline account
  2. Follow the steps to configure your account
  3. A clear idea of the plans you want to sell and their associated prices
  4. An API key to use the Hyperline API

When signed up and landed on Hyperline, you can use the Test mode to experiment before going live.

​
Steps

​
1. Model your products and plans in Hyperline

The first thing you need to do is to create your products and (optionally) plans in Hyperline.

You’ll need to do this operation once, but you can easily iterate on your pricing to experiment and adjust later.

If you need any assistance in representing the best way your offer or need advise, you can contact the support using the ‘Help’ chat.

​
2. Implement a subscription flow

Below is a suggested example of the flow to initiate a prospect’s subscription to your product. Of course, this may vary based on your specific use case and product and can be adjusted to suit your requirements.

1

The prospect create an account

For this example, the prospect initially signs up for your product by creating an account on your side.

2

Create a Hyperline customer

When the prospect signed up, your backend create a customer on Hyperline related to the newly signed up customer on your system.

curl --request POST \
  --url https://api.hyperline.co/v1/customers \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My customer",
    "currency": "EUR",
    "external_id": <ID of the customer in your system (optional if you want to keep the link easily)>
  }'
3

Assign a subscription

Then you can assign a subscription from the plan selected by the customer.

You need to use the ID corresponding to plans previously created, which can be found in Hyperline plans page (next to the plan name).

This example will create a dedicate checkout page for your customer to fill their billing details, add their payment method and subscribe. We’ll start the subscription from the current date and redirect back the customer to a specific URL (https://acme.com/api/callback) on your side after completing the checkout.

curl --request POST \
  --url https://api.hyperline.co/v2/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer_id": <ID from the previous call>,
    "plan_id": "plan_zHmjoDea4ZRmQV",
    "starts_at": "2023-12-20T00:00:00Z",
    "activation_strategy": "checkout",
    "payment_method_strategy": "new",
    "checkout_session": {
      "redirect_url": "https://myservice.com/api/callback"
    }
  }'

If your plan contains a seat-based product and you want to customize the quantity of items, you can use an additional parameter in the request body.

{
  "products": [
    {
      "id": "itm_4vea8Gj0a5HZr9",
      "count": 23
    }
  ],
}
4

Redirect to the subscription checkout

After creating the subscription, you’ll receive a checkout URL in the response payload.

"checkout_session": {
  "status": "opened",
  "url": "https://billing.hyperline.co/checkout/che_hEUPdVG7IgjpW1"
}

Redirect your customer to this URL for them to subscribe.

5

Handling subscription

When completed, the customer will be redirected to the final URL on your side (previously configured when creating the subscription). The customer is now successfully subscribed to your service.

You have the option to store this information on your end or entirely rely on Hyperline and retrieve the subscription status for the customer at any time.

curl --request GET \
  --url https://api.hyperline.co/v1/customers/<customer ID> \
  --header 'Authorization: Bearer <token>'

{
  "id": "cus_Typ0px2W0aiEtl",
  "name": "My customer",
  "currency": "EUR",
  "subscriptions": [
    {
      "id": "sub_0kIc7jrF7gV00V",
      "status": "active"
    }
  ]
}

If your plan contains a seat product representing a quantity of items, you can retrieve this quantity using the subscriptions API.

curl --request GET \
  --url https://api.hyperline.co/v2/subscriptions/<subscription ID> \
  --header 'Authorization: Bearer <token>'

{
  "status": "active",
  "products": [
    {
      "id": "itm_4vea8Gj0a5HZr9",
      "type": "seat",
      "count": 23
    }
  ],
}

That’s it! You can then proceed with the desired product flow.

Your customer will be automatically invoiced and their payment method charged according to the settings of the plan and the created subscription.

​
3. Follow the subscription

You’re able to retrieve at any time a unique portal link for your customer to follow their subscription, edit their payment method, or download their invoices.

We recommend adding a button in your product redirecting to this page for your customer to “manage billing”.

curl --request GET \
  --url https://api.hyperline.co/v1/customers/<customer ID>/portal \
  --header 'Authorization: Bearer <token>'

{
  "url": "https://...",
}

On your side, you can fully follow and manage your customers’ subscriptions on Hyperline, also using the dashboard page to have an overview on your revenue.