Create plan

Route

POST

/api/v1/plans

Usage

Curl

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": "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": [
      {
        "billable_metric_id": "__BILLABLE_METRIC_ID__",
        "charge_model": "standard",
        "group_properties": [
          {
            "group_id": "__GROUP_ID__",
            "values": {
              "amount": "0.10"
            }
          }
        ]
      },
      {
        "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.001"
            },
            {
              "to_value": null,
              "from_value": 11,
              "flat_amount": "0",
              "per_unit_amount": "0.0005"
            }
          ]
        }
      },
      {
        "billable_metric_id": "__BILLABLE_METRIC_ID__",
        "charge_model": "package",
        "properties": {
          "amount": "100",
          "free_units": 10000,
          "package_size": 1000
        }
      },
      {
        "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
        }
      },
      {
        "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"
            }
          ]
        }
      }
    ]
  }
}'

Python

from lago_python_client import Client
from lago_python_client.models import Plan, Charges, Charge

client = Client(api_key='__YOUR_API_KEY__')

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

graduated_charge = Charge(
  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(
  billable_metric_id='id,
  charge_model='package',
  properties={
    'amount': '100',
    'free_units': 10000,
    'package_size': 1000
  }
)

percentage_charge = Charge(
  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(
  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
)
client.plans().create(plan)

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: [
    {
      billable_metric_id: 'id',
      charge_model: 'standard',
      group_properties: [
        {
          group_id: 'group_id',
          values: {
            amount: '0.10'
          }
        }
      ]
    },
    {
      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'
        }
      ]
    },
    {
      billable_metric_id: 'id',
      charge_model: 'package',
      properties: {
        amount: '100',
        free_units: 10000,
        package_size: 1000
      }
    },
    {
      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
      }
    },
    {
      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.create(plan)

Node.js

import Plan from 'lago-nodejs-client/plan'
import Charge from 'lago-nodejs-client/charge'

let client = new Client('__API_KEY__')

let standardCharge = new Charge({
  billableMetricId: 'id',
  chargeModel: 'standard',
  groupProperties: [
    {
      groupId: 'group_id',
      values: {
        amount: '0.10'
      }
    }
  ]
})

let graduatedCharge = new Charge({
  billableMetricId: 'id',
  chargeModel: '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'
    }
  ]
})

let packageCharge = new Charge({
  billableMetricId: 'id',
  chargeModel: 'package',
  properties: {
    amount: '100',
    free_units: 10000,
    package_size: 1000
  }
})

let percentageCharge = new Charge({
  billableMetricId: 'id',
  chargeModel: 'percentage',
  properties: {
    rate: '0.5',
    fixed_amount: '1',
    free_units_per_events: 3,
    free_units_per_total_aggregation: nil
  }
})

let volumeCharge = new Charge({
  billableMetricId: 'id',
  chargeModel: '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'
      }
    ]
  }
})

let charges = [
  standardCharge,
  packageCharge,
  graduatedCharge,
  percentageCharge,
  volumeCharge,
]

let plan = new Plan(
  {
    name: 'name1',
    code: 'code1',
    interval: 'weekly',
    amountCents: 1000,
    amountCurrency: 'USD',
    payInAdvance: true,
    trialPeriod: 2,
    description: 'decs',
    billChargesMonthly: false,
    charges: charges,
})
await client.createPlan(plan);

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,
    }

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

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

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": [
      {
        "billable_metric_id": "__BILLABLE_METRIC_ID__",
        "charge_model": "standard",
        "group_properties": [
          {
            "group_id": "__GROUP_ID__",
            "values": {
              "amount": "0.10"
            }
          }
        ]
      },
      {
        "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"
            }
          ]
        }
      },
      {
        "billable_metric_id": "__BILLABLE_METRIC_ID__",
        "charge_model": "package",
        "properties": {
          "amount": "100",
          "free_units": 10000,
          "package_size": 1000
        }
      },
      {
        "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
        }
      },
      {
        "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      Required	Plan name
code	String      Required	Code identifying the Plan
interval	String      Required	Interval used for subscription billing. It can be yearly, ,monthly or weekly
description	String      Optional	Description of the plan
amount_cents	Integer      Required	Amount of the plan
amount_currency	String      Required	Currency of the amount
trial_period	Float      Optional	Number of free days.
pay_in_advance	Boolean      Required	Field specifying if payment in advance or in arrear will be used.
bill_charges_monthly	Boolean      Optional	Monthly billing will be applied on yearly plan if this field is set to true.

Charge attributes

Attributes	Type	Description
billable_metric_id	String      Required	Billable metric id in lago application
charge_model	String      Required	Charge model used in event calculations. It can be standard, graduated, package, percentage or volume
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	Price of one aggregated unit

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 to apply to each aggregated unit between the boundaries
flat_amount	String Required Decimal value	Flat amount 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
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 that applies to the total amount
fixed_amount	String Decimal value	Fee 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 to apply to each aggregated unit
flat_amount	String Required Decimal value	Flat amount to add to the result if the range is reached

Responses

HTTP 200

The plan was created

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": "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

  • 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	The 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