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)

API

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 and deleting Plans

Plans can be edited and deleted only if they are not linked to a Customer (meaning there is no active subscription for this Plan).

If you want to make a change to a Plan already linked to a Customer, you have 2 options:

1. Remove all active subscriptions
2. Create a new Plan