Overview

If Billable metrics are made to measure customer usage, Plans are made to apply prices to this usage.

Note that you don’t need to define a Billable metric to create a Plan. However, if you have usage feature to charge, the price of your Billable metrics is defined inside each Plan. Make sure to understand how to create a Billable metric first.

Plan structure

A Plan defines the features your customers have access to, the prices paid to access them and the invoicing cadence. In order to invoice a Customer with Lago, you must assign a Plan to a customer.

But first, let’s define the structure of a Plan:

Dashboard

1. The Plan basic informations
   • A Plan name
   • A Plan code
   • A Plan description
2. The Plan model
   • A Plan interval
   • A Plan base amount with the currency
   • Boolean to define if the Plan is paid in advance or in arrears
   • A Plan trial period in days
   • Taxes applied to this plan
3. The additional charges for this Plan (any Billable metrics that have been created)
   • A Charge model
   • A Charge amount and its currency (automatically inherited from the currency of the Plan)
   • A Charge spending minimum
   • Boolean to define if the Charge is paid in advance or in arrears
   • Taxes applied to this charge (overriding the one defined on the plan)

1. The Plan basic informations
   • A Plan name
   • A Plan code
   • A Plan description
2. The Plan model
   • A Plan interval
   • A Plan base amount with the currency
   • Boolean to define if the Plan is paid in advance or in arrears
   • A Plan trial period in days
   • Taxes applied to this plan
3. The additional charges for this Plan (any Billable metrics that have been created)
   • A Charge model
   • A Charge amount and its currency (automatically inherited from the currency of the Plan)
   • A Charge spending minimum
   • Boolean to define if the Charge is paid in advance or in arrears
   • Taxes applied to this charge (overriding the one defined on the plan)

Premium Plan Example

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

curl --location --request POST "$LAGO_URL/api/v1/plans" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
   "plan": {
      "name": "Premium",
      "code": "premium",
      "interval": "monthly",
      "description": "Premium plan for SMB customers",
      "amount_cents": 50000,
      "amount_currency": "USD",
      "trial_period": 3.0,
      "pay_in_advance": true,
      "bill_charges_monthly": true,
      "tax_codes": ["french_standard_vat"],
      "charges": [
         {
         "billable_metric_id": "__BILLABLE_METRIC_ID__",
         "charge_model": "graduated",
         "pay_in_advance": false,
         "invoiceable": true,
         "min_amount_cents": 0,
         "tax_codes": ["french_standard_vat"],
         "properties": {
            "graduated_ranges": [
               {
                  "to_value": 10,
                  "from_value": 0,
                  "flat_amount": "0",
                  "per_unit_amount": "0.001"
               },
               {
                  "to_value": null,
                  "from_value": 11,
                  "flat_amount": "0",
                  "per_unit_amount": "0.0005"
               }
            ]
         }
      }
      ]
   }
}'

Editing Plans

Plans can be fully edited as long as they are not linked to a customer (i.e., no active subscriptions). Once a plan is assigned to a customer, you can modify subscription prices, add or remove charges, and adjust them. However, other settings—such as the “plan interval,” “pay in advance” options, and pro-rated charges—become fixed and cannot be edited once assigned to a customer.

Any edits to a plan will instantly impact all subscriptions linked to it.

Please note: If this plan is linked to overridden subscriptions, you can choose to cascade or not these changes to these overridden subscriptions. When updating a plan via the API, use the cascade_updates: true property to ensure that overridden subscriptions are impacted by the changes.

To update plans that are already linked to customers, you will need to either remove all active subscriptions or create a new plan.

To update a specific charge in a plan, the charge must first be removed, then re-added with the updated details.

Deleting Plans

Plans can be deleted regardless of whether they are linked to a subscription.

Deleting a plan that is linked to a subscription will automatically terminate the subscription, and invoices will be generated.

Assistant

Responses are generated using AI and may contain mistakes.