Skip to main content

Create plan

Route

POST
/api/v1/plans

Usage

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"
}
]
}
}
]
}
}'

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

AttributesTypeDescription
nameString      RequiredPlan name
codeString      RequiredCode identifying the Plan
intervalString      RequiredInterval used for subscription billing.
It can be yearly, ,monthly or weekly
descriptionString      OptionalDescription of the plan
amount_centsInteger      RequiredAmount of the plan
amount_currencyString      RequiredCurrency of the amount
trial_periodFloat      OptionalNumber of free days.
pay_in_advanceBoolean      RequiredField specifying if payment in advance or in arrear will be used.
bill_charges_monthlyBoolean      OptionalMonthly billing will be applied on yearly plan if this field is set to true.

Charge attributes

AttributesTypeDescription
billable_metric_idString      RequiredBillable metric id in lago application
charge_modelString      RequiredCharge model used in event calculations.
It can be standard, graduated, package, percentage or volume
propertiesJSON      OptionalExtra data to use for the event calculations.
group_propertiesArray      OptionalExtra data scoped by groups to use for the event calculations.

Group Properties

AttributesTypeDescription
group_idString      RequiredGroup id in lago application
valuesJSON      RequiredExtra data to use for the event calculations.

Standard charge model

AttributesTypeDescription
amountString
Required
Decimal
Price of one aggregated unit

Graduated charge model

  • Model:
AttributesTypeDescription
graduated_rangesArray
Required
Graduated ranges, sorted from bottom to top boundaries
  • Graduated Ranges:
AttributesTypeDescription
from_valueInteger
Required
Lower value of the range.
- Must be 0 or previous range to_value + 1
to_valueIntegerTop value of the range.
- Must be higher than the range from_value.
- Must be null on last range
per_unit_amountString
Required
Decimal value
Amount to apply to each aggregated unit between the boundaries
flat_amountString
Required
Decimal value
Flat amount to add to the result if the range is reached

Package charge model

AttributesTypeDescription
amountString
Required
Decimal value
Price of one package
package_sizeInteger
Required
Number of aggregated units per package
free_unitsInteger
Required
Number of aggregated units to exclude before applying the charge model

Percentage charge model

AttributesTypeDescription
rateString
Required
Decimal value
Charge rate that applies to the total amount
fixed_amountString
Decimal value
Fee that applies to each event ingested during the billing period
free_units_per_eventsIntegerNumber of events that are not subject to the fixed fee
free_units_per_total_aggregationString
Decimal value
Amount that is not subject to the charge rate

Volume charge model

  • Model:
AttributesTypeDescription
volume_rangesArray
Required
Volume ranges, sorted from bottom to top boundaries
  • Volume Ranges:
AttributesTypeDescription
from_valueInteger
Required
Lower value of the range.
- Must be 0 or previous range to_value + 1
to_valueIntegerTop value of the range.
- Must be higher than the range from_value.
- Must be null on last range
per_unit_amountString
Required
Decimal value
Amount to apply to each aggregated unit
flat_amountString
Required
Decimal value
Flat amount to add to the result if the range is reached

Responses

The plan was created

Returns a plan object.