Update plan

Route

PUT

/api/v1/plans/:code

Usage

Curl

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

curl --location --request PUT "$LAGO_URL/api/v1/plans/__plan_code__" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
  "plan": {
    "name": "Basic",
    "code": "basic",
    "interval": "yearly",
    "description": "This is a basic plan description",
    "amount_cents": 90000,
    "amount_currency": "USD",
    "trial_period": 3.0,
    "pay_in_advance": true,
    "bill_charges_monthly": true,
    "charges": [
      {
        "id": "__CHARGE_ID__",
        "billable_metric_id": "__BILLABLE_METRIC_ID__",
        "charge_model": "standard",
        "pay_in_advance": false,
        "min_amount_cents": 0,
        "group_properties": [
          {
            group_id: "__GROUP_ID__",
            values: {
              "amount": "0.10"
            }
          }
        ]
      },
      {
        "id": "__CHARGE_ID__",
        "billable_metric_id": "__BILLABLE_METRIC_ID__",
        "charge_model": "graduated",
        "pay_in_advance": false,
        "min_amount_cents": 0,
        "properties": {
          "graduated_ranges": [
            {
              "to_value": 10,
              "from_value": 0,
              "flat_amount": "0",
              "per_unit_amount": "0.00010"
            },
            {
              "to_value": null,
              "from_value": 11,
              "flat_amount": "0",
              "per_unit_amount": "0.0005"
            }
          ]
        }
      },
      {
        "id": "__CHARGE_ID__",
        "billable_metric_id": "__BILLABLE_METRIC_ID__",
        "charge_model": "package",
        "pay_in_advance": false,
        "min_amount_cents": 0,
        "properties": {
          "amount": "100",
          "free_units": 10000,
          "package_size": 1000
        }
      },
      {
        "id": "__CHARGE_ID__",
        "billable_metric_id": "__BILLABLE_METRIC_ID__",
        "charge_model": "percentage",
        "pay_in_advance": false,
        "min_amount_cents": 0,
        "properties": {
          "rate": "0.5",
          "fixed_amount": "1",
          "free_units_per_events": 3,
          "free_units_per_total_aggregation": null
        }
      },
      {
        "id": "__CHARGE_ID__",
        "billable_metric_id": "__BILLABLE_METRIC_ID__",
        "charge_model": "volume",
        "pay_in_advance": false,
        "min_amount_cents": 0,
        "properties": {
          "volume_ranges": [
            {
              "to_value": 10,
              "from_value": 0,
              "flat_amount": "0",
              "per_unit_amount": "0.00010"
            },
            {
              "to_value": null,
              "from_value": 11,
              "flat_amount": "0",
              "per_unit_amount": "0.0005"
            }
          ]
        }
      }
    ]
  }
}'

Python

from lago_python_client.client import Client
from lago_python_client.exceptions import LagoApiError
from lago_python_client.models import Plan, Charges, Charge

client = Client(api_key='__YOUR_API_KEY__')

standard_charge = Charge(
  id='id',
  billable_metric_id='id',
  charge_model='standard',
  group_properties=[
    {
      group_id='group_id',
      values={
        'amount': '0.22'
      }
    }
  ]
)

graduated_charge = Charge(
  id='id',
  billable_metric_id='id,
  charge_model='graduated',
  properties=[
    {
      'to_value': 10,
      'from_value': 0,
      'flat_amount': '0',
      'per_unit_amount': '0.00010'
    },
    {
      'to_value': None,
      'from_value': 11,
      'flat_amount': "0",
      'per_unit_amount': '0.0005'
    }
  ]
)

package_charge = Charge(
  id='id',
  billable_metric_id='id,
  charge_model='package',
  properties={
    'amount': '100',
    'free_units': 10000,
    'package_size': 1000
  }
)

percentage_charge = Charge(
  id='id',
  billable_metric_id='id,
  charge_model='percentage',
  properties={
    'rate': '0.5',
    'fixed_amount': '1',
    'free_units_per_events': 3,
    'free_units_per_total_aggregation': None
  }
)

volume_charge = Charge(
  id='id',
  billable_metric_id='id,
  charge_model='volume',
  properties={
    'volume_ranges': [
      {
        'to_value': 10,
        'from_value': 0,
        'flat_amount': '0',
        'per_unit_amount': '0.00010'
      },
      {
        'to_value': None,
        'from_value': 11,
        'flat_amount': '0',
        'per_unit_amount': '0.0005'
      }
    ]
  }
)

charges = Charges(__root__=[
  standard_charge,
  graduated_charge,
  package_charge,
  percentage_charge,
  volume_charge
])

plan = Plan(
  name='name',
  code='code_first',
  amount_cents=1000,
  amount_currency='EUR',
  description='desc',
  interval='weekly',
  pay_in_advance=True,
  charges=charges
)

try:
    client.plans.update(plan, "__identifier__")
except LagoApiError as e:
    repair_broken_state(e)  # do something on error or raise your own exception

Ruby

require 'lago-ruby-client'

client = Lago::Api::Client.new({api_key: '__YOUR_API_KEY__'})

plan = {
  name: 'plan name',
  code: 'code',
  interval: 'monthly',
  description: 'description',
  amount_cents: 100,
  amount_currency: 'EUR',
  pay_in_advance: false,
  charges: charges: [
    {
      id: 'id',
      billable_metric_id: 'id',
      charge_model: 'standard',
      group_properties: [
        {
          group_id: 'group_id',
          values: {
            amount: '0.10'
          }
        }
      ]
    },
    {
      id: 'id',
      billable_metric_id: 'id',
      charge_model: 'graduated',
      properties: [
        {
          to_value: 10,
          from_value: 0,
          flat_amount: '0',
          per_unit_amount: '0.00010'
        },
        {
          to_value: nil,
          from_value: 11,
          flat_amount: '0',
          per_unit_amount: '0.0005'
        }
      ]
    },
    {
      id: 'id',
      billable_metric_id: 'id',
      charge_model: 'package',
      properties: {
        amount: '100',
        free_units: 10000,
        package_size: 1000
      }
    },
    {
      id: 'id',
      billable_metric_id: 'id',
      charge_model: 'percentage',
      properties: {
        rate: '0.5',
        fixed_amount: '1',
        free_units_per_events: 3,
        free_units_per_total_aggregation: nil
      }
    },
    {
      id: 'id',
      billable_metric_id: 'id',
      charge_model: 'volume',
      properties: {
        volume_ranges: [
          {
            to_value: 10,
            from_value: 0,
            flat_amount: '0',
            per_unit_amount: '0.00010'
          },
          {
            to_value: nil,
            from_value: 11,
            flat_amount: '0',
            per_unit_amount: '0.0005'
          }
        ]
      }
    }
  ]
}

client.plans.update(plan, "__identifier__")

Javascript

await client.plans.updatePlan("code", { plan: { amountCents: 2000 } });

Go

  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
    lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

    planInput := &lago.PlanInput{
      Name:           "Plan Go",
      Code:           "plan_go",
      Interval:       lago.PlanMonthly,
      PayInAdvance:   true,
      AmountCents:    1500,
      AmountCurrency: lago.EUR,
    }

    planResult, err := lagoClient.Plan().Update(planInput)
    if err != nil {
      // Error is *lago.Error
      panic(err)
    }

    // plan is *lago.Plan
    fmt.Println(plan)
  }

C#

using System.Collections.Generic;
using System.Diagnostics;
using Org.OpenAPITools.Api;
using Org.OpenAPITools.Client;
using Org.OpenAPITools.Model;

namespace Example
{
  public class UpdatePlanExample
  {
      public static void Main()
      {
          Configuration.Default.BasePath = "https://api.getlago.com/api/v1";
          // Configure HTTP bearer authorization: bearerAuth
          Configuration.Default.AccessToken = "YOUR_ACCESS_TOKEN";

          var apiInstance = new PlansApi(Configuration.Default);
          var code = "example_code";  // string | Code of the existing plan
          var planInput = new PlanInput(); // PlanInput | Update an existing plan

          try
          {
              // Update an existing plan
              Plan result = apiInstance.UpdatePlan(code, planInput);
              Debug.WriteLine(result);
          }
          catch (ApiException e)
          {
              Debug.Print("Exception when calling PlansApi.UpdatePlan: " + e.Message );
              Debug.Print("Status Code: "+ e.ErrorCode);
              Debug.Print(e.StackTrace);
          }
      }
  }
}

PHP

<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer authorization: bearerAuth
$config = OpenAPI\Client\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new OpenAPI\Client\Api\PlansApi(
  // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
  // This is optional, `GuzzleHttp\Client` will be used as default.
  new GuzzleHttp\Client(),
  $config
);
$code = "example_code"; // string | Code of the existing plan
$plan_input = new \OpenAPI\Client\Model\PlanInput(); // \OpenAPI\Client\Model\PlanInput | Update an existing plan

try {
  $result = $apiInstance->updatePlan($code, $plan_input);
  print_r($result);
} catch (Exception $e) {
  echo 'Exception when calling PlansApi->updatePlan: ', $e->getMessage(), PHP_EOL;
}

Arguments

{
  "plan": {
    "name": "Basic",
    "code": "basic",
    "interval": "yearly",
    "description": "This is a basic plan description",
    "amount_cents": 90000,
    "amount_currency": "USD",
    "trial_period": 3.0,
    "pay_in_advance": true,
    "bill_charges_monthly": true,
    "charges": [
      {
        "id": "__CHARGE_ID__",
        "billable_metric_id": "__BILLABLE_METRIC_ID__",
        "charge_model": "standard",
        "group_properties": [
          {
            "group_id": "__GROUP_ID__",
            "values": {
              "amount": "0.10"
            }
          }
        ]
      },
      {
        "id": "__CHARGE_ID__",
        "billable_metric_id": "__BILLABLE_METRIC_ID__",
        "charge_model": "graduated",
        "properties": {
          "graduated_ranges": [
            {
              "to_value": 10,
              "from_value": 0,
              "flat_amount": "0",
              "per_unit_amount": "0.00010"
            },
            {
              "to_value": null,
              "from_value": 11,
              "flat_amount": "0",
              "per_unit_amount": "0.0005"
            }
          ]
        }
      },
      {
        "id": "__CHARGE_ID__",
        "billable_metric_id": "__BILLABLE_METRIC_ID__",
        "charge_model": "package",
        "properties": {
          "amount": "100",
          "free_units": 10000,
          "package_size": 1000
        }
      },
      {
        "id": "__CHARGE_ID__",
        "billable_metric_id": "__BILLABLE_METRIC_ID__",
        "charge_model": "percentage",
        "properties": {
          "rate": "0.5",
          "fixed_amount": "1",
          "free_units_per_events": 3,
          "free_units_per_total_aggregation": null
        }
      },
      {
        "id": "__CHARGE_ID__",
        "billable_metric_id": "__BILLABLE_METRIC_ID__",
        "charge_model": "volume",
        "properties": {
          "volume_ranges": [
            {
              "to_value": 10,
              "from_value": 0,
              "flat_amount": "0",
              "per_unit_amount": "0.00010"
            },
            {
              "to_value": null,
              "from_value": 11,
              "flat_amount": "0",
              "per_unit_amount": "0.0005"
            }
          ]
        }
      }
    ]
  }
}

Plan attributes

Attributes	Type	Description
name	String      Optional	Plan name
code	String      Optional	Code identifying the Plan Cannot be updated if the plan is linked to a subscription
interval	String      Optional	Interval used for subscription billing. It can be yearly, monthly or weekly Cannot be updated if the plan is linked to a subscription
description	String      Optional	Description of the plan
amount_cents	Integer      Optional	Amount of the plan (excluding tax) Cannot be updated if the plan is linked to a subscription
amount_currency	String      Optional	Currency of the amount Cannot be updated if the plan is linked to a subscription
trial_period	Float      Optional	Number of free days Cannot be updated if the plan is linked to a subscription
pay_in_advance	Boolean      Optional	Field specifying if payment in advance or in arrear will be used Cannot be updated if the plan is linked to a subscription
bill_charges_monthly	Boolean      Optional	Monthly billing will be applied on yearly plan if this field is set to true Cannot be updated if the plan is linked to a subscription

Charge attributes

Charges cannot be updated if the plan is linked to a subscription.

Attributes	Type	Description
id	String      Optional	Charge unique id in Lago application
billable_metric_id	String      Optional	Billable metric id in lago application
charge_model	String      Optional	Charge model used in event calculations. It can be standard, graduated, package, percentage or volume
pay_in_advance	Boolean      Optional	Field specifying if charge is pay_in_advance or not.
min_amount_cents	Integer      Optional	Spending minimum of the charge in cents (excluding tax).
properties	JSON      Optional	Extra data to use for the event calculations.
group_properties	Array      Optional	Extra data scoped by groups to use for the event calculations.

Group Properties

Attributes	Type	Description
group_id	String      Required	Group id in lago application
values	JSON      Required	Extra data to use for the event calculations.

Standard charge model

Attributes	Type	Description
amount	String Required Decimal	Unit price (excluding tax)

Graduated charge model

• Model:

Attributes	Type	Description
graduated_ranges	Array Required	Graduated ranges, sorted from bottom to top boundaries

• Graduated Ranges:

Attributes	Type	Description
from_value	Integer Required	Lower value of the range. - Must be 0 or previous range to_value + 1
to_value	Integer	Top value of the range. - Must be higher than the range from_value. - Must be null on last range
per_unit_amount	String Required Decimal value	Amount (excluding tax) to apply to each aggregated unit between the boundaries
flat_amount	String Required Decimal value	Flat amount (excluding tax) to add to the result if the range is reached

Package charge model

Attributes	Type	Description
amount	String Required Decimal value	Price of one package (excluding tax)
package_size	Integer Required	Number of aggregated units per package
free_units	Integer Required	Number of aggregated units to exclude before applying the charge model

Percentage charge model

Attributes	Type	Description
rate	String Required Decimal value	Charge rate (excluding tax) that applies to the total amount
fixed_amount	String Decimal value	Fee (excluding tax) that applies to each event ingested during the billing period
free_units_per_events	Integer	Number of events that are not subject to the fixed fee
free_units_per_total_aggregation	String Decimal value	Amount that is not subject to the charge rate

Volume charge model

• Model:

Attributes	Type	Description
volume_ranges	Array Required	Volume ranges, sorted from bottom to top boundaries

• Volume Ranges:

Attributes	Type	Description
from_value	Integer Required	Lower value of the range. - Must be 0 or previous range to_value + 1
to_value	Integer	Top value of the range. - Must be higher than the range from_value. - Must be null on last range
per_unit_amount	String Required Decimal value	Amount (excluding tax) to apply to each aggregated unit
flat_amount	String Required Decimal value	Flat amount (excluding tax) to add to the result if the range is reached

Responses

HTTP 200

The plan was updated

Returns a plan object.

HTTP 400

{
  "status": 400,
  "error": "Bad Request"
}

The plan json root is not present in the request body.

HTTP 401

{
  "status": 401,
  "error": "Unauthorized"
}

Access to the API endpoint is unhautorized.

Possible reasons are:

• The Authorization header is missing
• The Authorization header does not contain the API key
• The Api key is invalid or expired

HTTP 404

{
  "status": 404,
  "error": "Not Found",
  "code": "__CODE__"
}

Possible codes are:

• plan_not_found: The plan was not found
• billable_metrics_not_found: One or more of the billable metrics were not found.

HTTP 422

{
  "status": 422,
  "error": "Unprocessable entity",
  "code": "validation_errors",
  "error_details": {
    "field": ["error"]
  }
}

Possible errors:

• On plan attributes:

  Field	Code	Description
  name	value_is_mandatory	name value is missing
  code	value_is_mandatory	code value is missing
  code	value_already_exists	code value is already used for another plan
  amount_currency	value_is_invalid	Provided currency value is invalid

• On charge attributes:

  • Standard charge model:

  Field	Code	Description
  properties	invalid_amount	amount value is invalid
  min_amount_cents	not_compatible_with_pay_in_advance	min_amount_cents value is not permitted on pay_in_advance charges

  • Graduated charge model:

  Field	Code	Description
  properties	missing_graduated_ranges	Range values are missing
  properties	invalid_graduated_ranges	One of the range attributes is invalid
  properties	invalid_amount	Value provided for per_unit_amount or flat_amount is invalid

  • Package charge model:

  Field	Code	Description
  properties	invalid_package_size	package_size value is invalid
  properties	invalid_free_units	free_units value is invalid
  properties	invalid_amount	amount value is invalid

  • Percentage charge model:

  Field	Code	Description
  properties	invalid_rate	rate value is invalid
  properties	invalid_fixed_amount	fixed_amount value is invalid
  properties	invalid_free_units_per_events	free_units_per_events value is invalid
  properties	invalid_free_units_per_total_aggregation	free_units_per_total_aggregation value is invalid

  • Volume charge model:

  Field	Code	Description
  properties	missing_volume_ranges	Range values are missing
  properties	invalid_volume_ranges	One of the range attributes is invalid
  properties	invalid_amount	Value provided for per_unit_amount or flat_amount is invalid