Overview

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:

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.