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",
        "properties": {
          "amount": "0.10"
        }
      },
      {
        "billable_metric_id": "__BILLABLE_METRIC_ID__",
        "charge_model": "graduated",
        "properties": [
          {
            "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": {
          "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',
  properties={
    '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={
    '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',
      properties: {
        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: {
        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',
  properties: {
    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: {
    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",
        "properties": {
          "amount": "0.10"
        }
      },
      {
        "billable_metric_id": "__BILLABLE_METRIC_ID__",
        "charge_model": "graduated",
        "properties": [
          {
            "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": {
          "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      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
-	Array Required	Graduated ranges, sorted from bottom to top boundaries

• 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
ranges	Array Required	Volume ranges, sorted from bottom to top boundaries

• 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",
  "message": "message"
}

Possible error messages:

• Validation error on the record