Skip to main content

Plan object

This object represents a plan.

Schema

{
"plan": {
"lago_id": "6bcba20e-cbc8-4975-a47b-2055eef34b22",
"name": "Basic",
"created_at": "2022-08-24T14:58:59Z",
"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,
"active_subscriptions_count": 0,
"draft_invoices_count": 0,
"charges": [
{
"lago_id": "27f12d13-4ae0-437b-b822-8771bcd62e3a",
"lago_billable_metric_id": "b09ce382-ce87-4da4-89f2-78b2060689fc",
"created_at": "2022-08-24T14:58:59Z",
"charge_model": "standard",
"group_properties": [
{
"group_id": "12345678-4ae0-437b-b822-8771bcd62e3a",
"values": {
"amount": "0.10"
}
}
]
},
{
"lago_id": "e530f658-c06a-44bb-a413-1fbe3796adb4",
"lago_billable_metric_id": "b09ce382-ce87-4da4-89f2-78b2060689fc",
"created_at": "2022-08-24T14:58:59Z",
"charge_model": "graduated",
"properties": {
"graduated_ranges": [
{
"to_value": 10,
"from_value": 0,
"flat_amount": "0",
"per_unit_amount": "10"
},
{
"to_value": null,
"from_value": 11,
"flat_amount": "0",
"per_unit_amount": "5"
}
]
}
},
{
"lago_id": "108051fc-c71b-47b4-bd86-47436ea6b639",
"lago_billable_metric_id": "b09ce382-ce87-4da4-89f2-78b2060689fc",
"created_at": "2022-08-24T14:58:59Z",
"charge_model": "package",
"properties": {
"amount": "100",
"free_units": 10000,
"package_size": 1000
}
},
{
"lago_id": "88b878e2-4ba4-4f37-98c9-ca8522a9e574",
"lago_billable_metric_id": "b09ce382-ce87-4da4-89f2-78b2060689fc",
"created_at": "2022-08-24T14:58:59Z",
"charge_model": "percentage",
"properties": {
"rate": "0.5",
"fixed_amount": "1",
"free_units_per_events": 3,
"free_units_per_total_aggregation": null
}
},
{
"lago_id": "e530f658-c06a-44bb-a413-1fbe3796555",
"lago_billable_metric_id": "b09ce382-ce87-4da4-89f2-78b2060689fc",
"created_at": "2022-08-24T14:58:59Z",
"charge_model": "volume",
"properties": {
"volume_ranges": [
{
"to_value": 10,
"from_value": 0,
"flat_amount": "0",
"per_unit_amount": "10"
},
{
"to_value": null,
"from_value": 11,
"flat_amount": "0",
"per_unit_amount": "5"
}
]
}
}
]
}
}

Plan attributes

AttributesDescription
lago_id     String     Not nullUnique identifier of the plan in Lago application.
name     String     Not nullPlan name.
created_at     String     Not null    
ISO 8601 datetime in UTC
Date of plan creation.
code     String     Not nullCode identifying the plan.
interval     String     Not null
Interval that applies on subscription and specifies billing period.
Possible values
- yearly
- weekly
- monthly
description     StringPlan description.
amount_cents     Integer     Not nullAmount in cents.
amount_currency     String     Not nullCurrency of the amount.
trial_period     FloatNumber of days for free trial.
pay_in_advance     BooleanValue should be true for payment in advance and false for payment in arrear.
bill_charges_monthly     BooleanIt should be set to true if monthly billing is needed on yearly plan.
active_subscriptions_count     Integer     Not nullCount of active subscriptions attached to the plan. This field can be used to know the impact of deleting this plan.
draft_invoices_count     Integer     Not nullCount of draft invoices containing a subscription attached to the plan. This field can be used to know the impact of deleting this plan.

Charge attributes

AttributesDescription
lago_id     String     Not nullUnique identifier of the charge in Lago application.
lago_billable_metric_id     String     Not nullUnique identifier of the related billable metric in Lago application.
created_at     String     Not null    
ISO 8601 datetime in UTC
Date of charge creation.
charge_model     String     Not null
Charge model used in event calculations.
Possible values
- standard
- graduated
- package
- percentage
- volume
properties     JSONExtra data. This field will depend on selected charge_model
group_properties     ArrayExtra data scoped by groups. This field will depend on selected charge_model

Group Properties

AttributesDescription
group_id     String     Not nullGroup id in lago application
values     JSON     Not nullExtra data. This field will depend on selected charge_model and group

Standard charge model

AttributesDescription
amount     String     Not null    
Decimal value
Price of one aggregated unit

Graduated charge model

  • Model:
AttributesDescription
graduated_ranges     Array of ranges     Not nullGraduated ranges, sorted from bottom to top boundaries
  • Graduated Ranges:
AttributesDescription
from_value     Integer     Not nullLower value of the range.
- Must be 0 or previous range to_value + 1
to_value     IntegerTop value of the range.
- Must be higher than the range from_value.
- Must be null on last range.
per_unit_amount     String     Not null    
Decimal value
Amount to apply to each aggregated unit between the boundaries
flat_amount     String     Not null    
Decimal value
Flat amount to add to the result if the range is reached

Package charge model

AttributesDescription
amount     String     Not null    
Decimal value
Price of one package
package_size     Integer     Not nullNumber of aggregated units per package.
free_units     Integer     Not nullNumber of aggregated units to exclude before applying the charge model.

Percentage charge model

AttributesDescription
rate     String     Not null    
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     IntegerNumber 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:
AttributesDescription
volume_ranges     Array of ranges     Not nullVolume ranges, sorted from bottom to top boundaries
  • Volume Ranges:
AttributesDescription
from_value     Integer     Not nullLower value of the range.
- Must be 0 or previous range to_value + 1
to_value     IntegerTop value of the range.
- Must be higher than the range from_value.
- Must be null on last range.
per_unit_amount     String     Not null    
Decimal value
Amount to apply to each aggregated unit
flat_amount     String     Not null    
Decimal value
Flat amount to add to the result if the range is reached