Assign a plan to a customer

A subscription is created when a plan is assigned to a customer. You can assign a plan to a customer at any time (i.e. when the customer record is created or later on).

Dashboard

To assign a plan to a customer through the user interface:

1. Access the “Customers” section via the side menu;
2. Select a customer from the list;
3. In the “Overview” tab, click “Add a plan” on the right;
4. Select a plan (that you can overwrite if needed - see below);
5. Give a name to the subscription (name that will be displayed on the invoice - optional);
6. Give an id to the subscription (define your own subscription identifier - optional);
7. Set a subscription start date (start date of the subscription - see below);
8. Set a subscription end date (end date of the subscription - see below - optional);
9. Choose whether the subscription should be renewed at the beginning of the period or on its anniversary date (see below); and
10. Click “Add plan” to confirm;

To assign a plan to a customer through the user interface:

1. Access the “Customers” section via the side menu;
2. Select a customer from the list;
3. In the “Overview” tab, click “Add a plan” on the right;
4. Select a plan (that you can overwrite if needed - see below);
5. Give a name to the subscription (name that will be displayed on the invoice - optional);
6. Give an id to the subscription (define your own subscription identifier - optional);
7. Set a subscription start date (start date of the subscription - see below);
8. Set a subscription end date (end date of the subscription - see below - optional);
9. Choose whether the subscription should be renewed at the beginning of the period or on its anniversary date (see below); and
10. Click “Add plan” to confirm;

Assign a plan to a customer

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/subscriptions" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
  "subscription": {
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "plan_code": "premium",
    "external_id": "my_sub_12345789",
    "name": "Repository 1",
    "subscription_at": "2022-08-08T00:00:00Z",
    "billing_time": "anniversary"
  }
}'

When a subscription is active, Lago will automatically generate invoices for the customer according to the plan model. It will also start monitoring the customer’s consumption, which means that you can start pushing events related to this subscription.

The subscription date displayed in the app is based on the organization’s timezone.

Billing cycles

Optimize billing for your customers by assigning subscriptions based on either calendar dates or anniversary dates (the day they signed up).

Calendar billing period

By default, subscriptions are based on calendar periods. Therefore, if you assign a monthly plan to a customer on July 14th:

• The first invoice will be generated for the period July 14th to July 31st;
• The next invoice will be generated for the period August 1st to August 31st; and
• All future invoices will be generated for full calendar months.

When a subscription starts during the month, the subscription fee will be calculated on a pro rata basis according to the number of days.

Consider the following example:

Your customer signs up for the Premium plan, $50 monthly, on August 10th. There are 22 days left until the end of the month, including August 10th. Therefore, the subscription fee for August is: 22 days x $50 / 31 days = $35.48

Calendar billing cadence

By default, subscriptions are based on calendar periods. Therefore, if you assign a monthly plan to a customer on July 14th:

• The first invoice will be generated for the period July 14th to July 31st;
• The next invoice will be generated for the period August 1st to August 31st; and
• All future invoices will be generated for full calendar months.

When a subscription starts during the month, the subscription fee will be calculated on a pro rata basis according to the number of days.

Consider the following example:

Your customer signs up for the Premium plan, $50 monthly, on August 10th. There are 22 days left until the end of the month, including August 10th. Therefore, the subscription fee for August is: 22 days x $50 / 31 days = $35.48

Calendar billing cadence

Another option is to use the anniversary date of the subscription to define a custom billing period.

For example:

Your customer signs up for the Premium plan on August 10th. If you choose to align the billing cycle with the anniversary date of the subscription, the customer will be billed every 10th of the month. The first billing period will run from August 10th to September 9th.

Anniversary billing cadence

Subscription start date

By default, the subscription starts the day it is created. However, you can set a subscription date in the past or in the future. The subscription date displayed in the app is based on the organization’s timezone. However, you can decide to start a subscription in the past or in the future.

Start date in the past

If the start date of the subscription is in the past, the subscription is considered active.

Lago will not generate any invoices for past periods already completed.

The invoicing process varies depending on the plan model and billing cycle:

• If the plan includes a subscription fee to be paid in advance, it will be considered as already paid for the current period. The next invoice will include the usage-based charges for the current period and the subscription fee for the next period (see example 1 below); and
• If the plan includes a subscription fee to be paid in arrears, it will be included in the next invoice, together with the usage-based charges for the current period (see example 2 below).

Example 1: Start date in the past and subscription fee to be paid in advance

Illustration for start date in the past and subscription fee in advance

Example 2: Start date in the past and subscription fee to be paid in arrears

Illustration for start date in the past and subscription fee in advance

If the start date of the subscription is in the past, the subscription is considered active.

Lago will not generate any invoices for past periods already completed.

The invoicing process varies depending on the plan model and billing cycle:

• If the plan includes a subscription fee to be paid in advance, it will be considered as already paid for the current period. The next invoice will include the usage-based charges for the current period and the subscription fee for the next period (see example 1 below); and
• If the plan includes a subscription fee to be paid in arrears, it will be included in the next invoice, together with the usage-based charges for the current period (see example 2 below).

Example 1: Start date in the past and subscription fee to be paid in advance

Illustration for start date in the past and subscription fee in advance

Example 2: Start date in the past and subscription fee to be paid in arrears

Illustration for start date in the past and subscription fee in advance

If the start date of the subscription is in the future, the subscription is considered pending.

The invoicing process varies depending on the plan model and billing cycle:

• If the plan includes a subscription fee to be paid in advance, when the subscription becomes active, Lago will automatically generate an invoice for the subscription fee. Usage-based charges will be included in the next invoice, generated at the end of the billing period (see example 3 below); and
• If the plan includes a subscription fee to be paid in arrears, when the subscription becomes active, there will be no invoice. The subscription fee and usage-based charges will be included in the invoice generated at the end of the billing period (see example 4 below).

Example 3: Start date in the future and subscription fee to be paid in advance

Illustration for start date in the future and subscription fee in advance

Example 4: Start date in the future and subscription fee to be paid in arrears

Illustration for start date in the future and subscription fee in arrears

Subscription end date

By default, if no subscription end date is specified, the subscription will automatically renew at the end of the period.

However, if you define an end date, the subscription will terminate on that date without renewal. This is valuable for contracts with specific termination dates.

Keep in mind, 45 days and 15 days before the subscription ends, a webhook alert, called subscription.termination_alert, will remind you. You then have two choices:

1. Allow the subscription to continue until the end date and finalize it; or
2. Adjust the subscription end date if the contract has been renegotiated.

Ensure that the subscription end date is set to a date later than the subscription start date.

Dashboard

Here is how you can define a susbcription end date from the UI:

1. Access the “Customers” section via the side menu;
2. Select a customer from the list;
3. In the “Overview” tab, click “Add a plan” on the right;
4. Set a subscription start date;
5. Set a subscription end date;
6. Choose between calendar or anniversary billing;
7. Click “Add plan” to confirm.

Here is how you can define a susbcription end date from the UI:

1. Access the “Customers” section via the side menu;
2. Select a customer from the list;
3. In the “Overview” tab, click “Add a plan” on the right;
4. Set a subscription start date;
5. Set a subscription end date;
6. Choose between calendar or anniversary billing;
7. Click “Add plan” to confirm.

Use the ending_at field on the subscriptions endpoint.

Define a subscription end date

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/subscriptions" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
  "subscription": {
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "plan_code": "premium",
    "external_id": "my_sub_12345789",
    "name": "Repository 1",
    "subscription_at": "2022-08-08T00:00:00Z",
    "ending_at": "2023-08-08T00:00:00Z",
    "billing_time": "anniversary"
  }
}'

Multiple plans

You may create several subscriptions for a customer by assigning them multiple plans. This can be particularly useful if your application allows customers to create different projects or workspaces (e.g. Free plan for Workspace 1, Free plan for Workspace 2, Premium plan for Workspace 3, etc.).

There are some rules to keep in mind when assigning multiple plans to a customer:

1. All plans must be denominated in the same currency; and
2. You must specify the external_subscription_id for each event or create batch events.

It is possible to subscribe a customer to multiple plans using different billing cycles (e.g. a subscription based on calendar dates and another based on the anniversary date).

We recommend that you give each subscription a name when assigning multiple plans to a customer. The subscription names will make it easier to differentiate each plan and will also be displayed on the invoices.

When multiple subscriptions are linked to a customer, Lago will automatically consolidate invoices when possible.

	Month 1	Month 2	Month 3	Month 4	(…)	Month 13
Plan A (monthly)	$40	$40	$40	$40	(…)	$40
Plan B (monthly)	$60	$60	$60	$60	(…)	$60
Plan C (yearly)	$500	-	-	-	(…)	$500
Total invoice	$600	$100	$100	$100	(…)	$600

Overriding a plan

PREMIUM FEATURE ✨

This feature is only available to users with a premium license. Please contact us to get access to Lago Cloud and Lago Self-Hosted Premium.

By assigning a subscription to a customer, you gain the flexibility to customize certain aspects of the initially selected plan. This enables you to maintain a consistent plan structure for all customers while tailoring individualized discounts through price adjustments per customer.

Dashboard

To perform a plan overrides, assign a plan to a customer and you’ll be able to make modifications to the following elements:

1. Subscription invoice display name
2. Subscription fee
3. Plan currency
4. Plan trial period
5. Plan taxes
6. Charges properties (please note that the charge model cannot be modified)
7. Charge group definitions & properties (if applicable)
8. Charge minimum spending
9. Charge taxes
10. Charge invoice display name
11. Progressive billing thresholds

To perform a plan overrides, assign a plan to a customer and you’ll be able to make modifications to the following elements:

1. Subscription invoice display name
2. Subscription fee
3. Plan currency
4. Plan trial period
5. Plan taxes
6. Charges properties (please note that the charge model cannot be modified)
7. Charge group definitions & properties (if applicable)
8. Charge minimum spending
9. Charge taxes
10. Charge invoice display name
11. Progressive billing thresholds

Override a plan

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/subscriptions" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "subscription": {
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "plan_code": "premium",
    "external_id": "my_new_sub_123456789",
    "name": "",
    "subscription_at": "2022-08-08T00:00:00Z",
    "ending_at": "2023-08-08T00:00:00Z",
    "billing_time": "anniversary",
    "plan_overrides": {
      "name": "new_plan",
      "invoice_display_name": "Subscription fee",
      "description": "Overriden plan for customer X",
      "amount_cents": 10000,
      "amount_currency": "USD",
      "trial_period": "0",
      "tax_codes": [
        "vat_10"
      ],
      "charges": [
        {
          "id": "cac4cff7-e2d9-41e2-83e5-7947d91f0eb5",
          "invoice_display_name": "Cards - custom price",
          "billable_metric_code": "cards",
          "min_amount_cents": 0,
          "properties": {
            "amount": "10"
          },
          "group_properties": [],
          "taxes": []
        }
      ]
    }
  }
}'

It’s crucial to note that all overridden plans will remain associated with the initial plan but won’t be visible in the plans list. To access an overridden plan, simply click on the specific subscription item in the customer details view.

Moreover, all invoices generated from this subscription will be based from the overridden plan, not the initial plan. Additionally, any coupons restricted to a plan code will apply to both the initial and overridden plans.

Importantly, any changes made to the initial plans will not impact the subscriptions linked to overridden plans.

Deleting a plan

You could delete a plan linked to existing subscriptions.

If you do so, the subscriptions associated with this plan will be immediately terminated. This action may trigger the generation of invoices and/or credit notes.

After deleting a plan, you can create a new one using the same code.

Assistant

Responses are generated using AI and may contain mistakes.