Assign a plan to a customer

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;

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

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.

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

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

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

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

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

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.

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"
  }
}'

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