Skip to main content
In this guide, we will see how to implement Hyperline subscriptions 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 a 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 templates in Hyperline

The first thing you need to do is to create your products and (optionally) subscription templates 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 advice, you can contact 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 creates 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 signs up, your backend creates 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": <(optional) ID of the customer in your system>,
    "available_payment_methods": <(optional) list of authorized payment methods>
  }'
3

Assign a subscription

Then you can assign a subscription from the template (representing your plans/offers) selected by the customer.You need to use the ID corresponding to the template previously created, which can be found in Hyperline templates (next to the template name).This example creates a dedicated checkout page for your customer to fill in their billing details, add their payment method and subscribe. The subscription starts from the current date, and the customer is redirected to a specific URL on your side (https://myservice.com/api/callback) after completing the checkout.Use checkout_session.redirect_url to set the URL where the customer should be redirected after checkout completion.
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>,
    "template_id": "subt_ji3uPodOneXk6R",
    "starts_at": "2025-12-20T00:00:00Z",
    "activation_strategy": "checkout",
    "checkout_session": {
      "redirect_url": "https://myservice.com/api/callback"
    }
  }'
If you want to customize the quantity of products, 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 the hosted checkout page URL in checkout_session.url in the response payload.
"checkout_session": {
  "status": "opened",
  "url": "https://billing.hyperline.co/checkout/che_hEUPdVG7IgjpW1"
}
Redirect your customer to checkout_session.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 you want to retrieve the quantity of the subscription products or the full details, you can use 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 your desired product flow. Your customer will be automatically invoiced and their payment method charged according to the configuration of 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://..."
}
You can also follow and manage your customers’ subscriptions on Hyperline.