Skip to main content
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 override 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. Define a PO number to be used on invoices generated from this subscription;
  10. Choose whether the subscription should be renewed at the beginning of the period or on its anniversary date (see below);
  11. Under “Subscription activation rule”, select “Activate on successful payment” to hold the subscription until its first payment succeeds (see Activation rules - optional);
  12. In “Invoicing settings”, choose “Consolidate invoices” or “Isolate invoices” (see below - optional); and
  13. Click “Assign plan” to confirm.
When a subscription is active, Lago generates invoices for the customer according to the plan model. It also starts monitoring the customer’s consumption, so you can start pushing events related to this subscription.
The subscription date displayed in the app is based on the organization’s timezone.
Want to hold activation until the first payment clears, so you never open AR for an unpaid subscription? See Activation rules.

Payment terms

Payment terms determine when the subscription’s invoices are due. When assigning a plan, open Invoicing settings and choose a term for this subscription, or keep the inherited customer term. If the customer has no term of their own, the billing entity’s default applies. For example, keep Net 30 for a standard subscription and choose Net 60 for an enterprise subscription belonging to the same customer. For invoices dated April 10, 2026, payment is due on May 10 and June 9, respectively. The different terms require separate invoices. See Payment terms for all six options and dated examples. You can also change an existing subscription’s term. When you upgrade or downgrade the plan, the new subscription keeps this term unless you set a different one during the change. From the API, send payment_term when you create the subscription. This endpoint does not accept the legacy net_payment_term field: if you send it, Lago ignores it and the inherited term applies.

Billing cycles

Bill your customers on calendar dates or on the anniversary date of the subscription (the day they signed up).
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
Timeline of a monthly subscription billed on calendar periods.

Calendar billing cadence

Subscription start date

By default, the subscription starts the day it is created. However, you can decide to start a subscription in the past or in the future.
If the start date of the subscription is in the past, the subscription is considered active.
Lago does not generate invoices for past periods that are 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
Timeline of a subscription starting in the past, with the subscription fee 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
Timeline of a subscription starting in the past, with the subscription fee paid in arrears.

Illustration for start date in the past 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. 45 days and 15 days before the subscription ends, Lago sends a subscription.termination_alert webhook to 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.
Here is how you can define a subscription 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 “Assign plan” to confirm.

Multiple plans

You can 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 (for example Free plan for Workspace 1, Free plan for Workspace 2, Premium plan for Workspace 3).
When assigning multiple plans to a customer, you must specify the external_subscription_id for each event or create batch events.
You can subscribe a customer to multiple plans using different billing cycles, for example one based on calendar dates and another based on the anniversary date. Give each subscription a name when you assign multiple plans to a customer. The names make each plan easier to tell apart, and they appear on the invoices.

Invoice consolidation

When a customer is subscribed to multiple plans, Lago can either group all subscription charges into a single consolidated invoice or issue a separate invoice for each subscription. By default, Lago consolidates subscriptions into a single invoice when they are billed on the same day and share all of the following:
  • The same payment method;
  • The same currency;
  • The same billing entity;
  • The same PO number (purchase_order_number); and
  • The same effective payment term.
The effective term is the term that applies after checking subscription, customer, and billing-entity settings. A subscription that inherits Net 30 and one explicitly set to Net 30 share an invoice. A Net 30 subscription and a Net 60 subscription get separate invoices. Terms that always produce the same due date count as the same term. For example, Net 0 and Due on receipt share an invoice, and so do End of month and Net 0 days after end of month. This reduces the number of invoices your customers receive and simplifies payment reconciliation. In the example below, a customer is subscribed to three plans, two billed monthly and one billed yearly, and Lago groups all charges that fall on the same billing date into a single invoice: To keep a specific subscription on its own invoice, for example to bill a different cost center, track a contract independently, or simplify internal reporting, disable consolidation for that subscription. Set the consolidate_invoice field to false on the subscription, either from the dashboard or via the API. Lago then issues a standalone invoice for that subscription, even when other subscriptions for the same customer are billed on the same day.
The consolidate_invoice setting applies at the subscription level, so you can mix consolidated and standalone subscriptions for the same customer. You can update this setting at any time.

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.
When you assign a plan to a customer, you can customize parts of it for that subscription. You keep one plan structure for every customer, and adjust prices per customer where you need to.
To override a plan, assign it to a customer. You can then change:
  1. Subscription invoice display name
  2. Subscription fee
  3. Plan currency
  4. Plan trial period
  5. Plan taxes
  6. Charge properties (the charge model cannot be changed)
  7. Filters and their properties (if applicable)
  8. Charge minimum spending
  9. Charge taxes
  10. Charge invoice display name
  11. Progressive billing thresholds
Fixed charges are also overridden under plan_overrides, using the fixed_charges array. Sending only units (and apply_units_immediately if needed) updates the quantity without creating a plan override. Passing a price or properties creates one. See Update a fixed charge via the API.
An overridden plan stays linked to the initial plan, but it does not appear in the plans list. To open it, click the subscription in the customer details view. All invoices generated from this subscription are based on the overridden plan, not the initial plan. Coupons restricted to a plan code apply to both the initial plan and its overrides. By default, changes made to the initial plan do not reach subscriptions linked to an overridden plan. To propagate them, update the plan with cascade_updates set to true. See Editing plans.

Deleting a plan

You can delete a plan that is 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.