The plan object

{
  "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
  "name": "Startup",
  "created_at": "2023-06-27T19:43:42Z",
  "code": "startup",
  "interval": "monthly",
  "amount_cents": 10000,
  "amount_currency": "USD",
  "invoice_display_name": "Startup plan",
  "description": "",
  "trial_period": 5,
  "pay_in_advance": true,
  "bill_charges_monthly": null,
  "bill_fixed_charges_monthly": null,
  "minimum_commitment": {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "amount_cents": 100000,
    "created_at": "2022-04-29T08:59:51Z",
    "plan_code": "premium",
    "invoice_display_name": "Minimum Commitment (C1)",
    "interval": "monthly",
    "updated_at": "2022-04-29T08:59:51Z",
    "taxes": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "name": "TVA",
        "code": "french_standard_vat",
        "rate": 20,
        "applied_to_organization": true,
        "created_at": "2023-07-06T14:35:58Z",
        "description": "French standard VAT",
        "applied_to_billing_entities_codes": [
          "acme_corp",
          "foo_bar"
        ]
      }
    ]
  },
  "charges": [
    {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a91",
      "lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a91",
      "billable_metric_code": "requests",
      "created_at": "2023-06-27T19:43:42Z",
      "charge_model": "package",
      "invoiceable": true,
      "invoice_display_name": "Setup",
      "pay_in_advance": false,
      "regroup_paid_fees": null,
      "prorated": false,
      "min_amount_cents": 3000,
      "properties": {
        "amount": "30",
        "free_units": 100,
        "package_size": 1000
      },
      "filters": []
    },
    {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a92",
      "lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a92",
      "billable_metric_code": "cpu",
      "created_at": "2023-06-27T19:43:42Z",
      "charge_model": "graduated",
      "invoiceable": true,
      "invoice_display_name": "Setup",
      "pay_in_advance": false,
      "regroup_paid_fees": null,
      "prorated": false,
      "min_amount_cents": 0,
      "properties": {
        "graduated_ranges": [
          {
            "from_value": 0,
            "to_value": 10,
            "flat_amount": "10",
            "per_unit_amount": "0.5"
          },
          {
            "from_value": 11,
            "to_value": null,
            "flat_amount": "0",
            "per_unit_amount": "0.4"
          }
        ]
      },
      "filters": []
    },
    {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a93",
      "lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a93",
      "billable_metric_code": "seats",
      "created_at": "2023-06-27T19:43:42Z",
      "charge_model": "standard",
      "invoiceable": true,
      "invoice_display_name": "Setup",
      "pay_in_advance": true,
      "regroup_paid_fees": null,
      "prorated": false,
      "min_amount_cents": 0,
      "properties": {},
      "filters": [
        {
          "invoice_display_name": "Europe",
          "properties": {
            "amount": "10"
          },
          "values": {
            "region": [
              "Europe"
            ]
          }
        },
        {
          "invoice_display_name": "USA",
          "properties": {
            "amount": "5"
          },
          "values": {
            "region": [
              "USA"
            ]
          }
        },
        {
          "invoice_display_name": "Africa",
          "properties": {
            "amount": "8"
          },
          "values": {
            "region": [
              "Africa"
            ]
          }
        }
      ]
    },
    {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a94",
      "lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a94",
      "billable_metric_code": "storage",
      "created_at": "2023-06-27T19:43:42Z",
      "charge_model": "volume",
      "invoiceable": true,
      "invoice_display_name": "Setup",
      "pay_in_advance": false,
      "regroup_paid_fees": null,
      "prorated": false,
      "min_amount_cents": 0,
      "properties": {
        "volume_ranges": [
          {
            "from_value": 0,
            "to_value": 100,
            "flat_amount": "0",
            "per_unit_amount": "0"
          },
          {
            "from_value": 101,
            "to_value": null,
            "flat_amount": "0",
            "per_unit_amount": "0.5"
          }
        ]
      },
      "filters": []
    },
    {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a95",
      "lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a95",
      "billable_metric_code": "payments",
      "created_at": "2023-06-27T19:43:42Z",
      "charge_model": "percentage",
      "invoiceable": false,
      "invoice_display_name": "Setup",
      "pay_in_advance": true,
      "regroup_paid_fees": "invoice",
      "prorated": false,
      "min_amount_cents": 0,
      "properties": {
        "rate": "1",
        "fixed_amount": "0.5",
        "free_units_per_events": 5,
        "free_units_per_total_aggregation": "500"
      },
      "filters": []
    }
  ],
  "fixed_charges": [
    {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "lago_add_on_id": "2b802b80-2b80-2b80-2b80-2b802b802b80",
      "code": "setup_fee",
      "invoice_display_name": "Setup Fee",
      "add_on_code": "setup",
      "created_at": "2026-01-15T10:30:00Z",
      "charge_model": "standard",
      "pay_in_advance": true,
      "prorated": false,
      "properties": {
        "amount": "500"
      },
      "units": 1,
      "lago_parent_id": null,
      "taxes": [
        {
          "lago_id": "3c703c70-3c70-3c70-3c70-3c703c703c70",
          "name": "VAT",
          "code": "vat_20",
          "rate": 20,
          "description": "Standard VAT rate",
          "applied_to_organization": true,
          "created_at": "2026-01-01T00:00:00Z"
        }
      ]
    },
    {
      "lago_id": "4d604d60-4d60-4d60-4d60-4d604d604d60",
      "lago_add_on_id": "5e505e50-5e50-5e50-5e50-5e505e505e50",
      "code": "support_tier",
      "invoice_display_name": "Support Tier",
      "add_on_code": "premium_support",
      "created_at": "2026-01-15T10:30:00Z",
      "charge_model": "graduated",
      "pay_in_advance": false,
      "prorated": true,
      "properties": {
        "graduated_ranges": [
          {
            "from_value": 0,
            "to_value": 10,
            "per_unit_amount": "5",
            "flat_amount": "200"
          },
          {
            "from_value": 11,
            "to_value": null,
            "per_unit_amount": "1",
            "flat_amount": "300"
          }
        ]
      },
      "units": 1,
      "lago_parent_id": null,
      "taxes": []
    },
    {
      "lago_id": "6f406f40-6f40-6f40-6f40-6f406f406f40",
      "lago_add_on_id": "7a307a30-7a30-7a30-7a30-7a307a307a30",
      "code": "storage",
      "invoice_display_name": "Storage Allocation",
      "add_on_code": "cloud_storage",
      "created_at": "2026-01-15T10:30:00Z",
      "charge_model": "volume",
      "pay_in_advance": false,
      "prorated": false,
      "properties": {
        "volume_ranges": [
          {
            "from_value": 0,
            "to_value": 100,
            "per_unit_amount": "2",
            "flat_amount": "1"
          },
          {
            "from_value": 101,
            "to_value": null,
            "per_unit_amount": "1",
            "flat_amount": "0"
          }
        ]
      },
      "units": 50,
      "lago_parent_id": null,
      "taxes": []
    }
  ],
  "taxes": [
    {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "name": "TVA",
      "code": "french_standard_vat",
      "rate": 20,
      "applied_to_organization": true,
      "created_at": "2023-07-06T14:35:58Z",
      "description": "French standard VAT",
      "applied_to_billing_entities_codes": [
        "acme_corp",
        "foo_bar"
      ]
    }
  ],
  "usage_thresholds": [
    {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "threshold_display_name": "Threshold 1",
      "amount_cents": 10000,
      "recurring": true,
      "created_at": "2023-06-27T19:43:42Z",
      "updated_at": "2023-06-27T19:43:42Z"
    }
  ],
  "entitlements": [
    {
      "entitlement": {
        "code": "seats",
        "name": "Number of seats",
        "description": "Number of users of the account",
        "privileges": [
          {
            "code": "max",
            "name": "Maximum",
            "value_type": "integer",
            "config": {},
            "value": 10
          },
          {
            "code": "max_admins",
            "name": "Max Admins",
            "value_type": "integer",
            "config": {},
            "value": 5
          },
          {
            "code": "root",
            "name": "Allow root user",
            "value_type": "boolean",
            "config": {},
            "value": true
          },
          {
            "code": "provider",
            "name": "SSO Provider",
            "value_type": "select",
            "value": "google",
            "config": {
              "select_options": [
                "google",
                "okta"
              ]
            }
          }
        ]
      }
    }
  ],
  "metadata": {
    "external_id": "ext-123",
    "synced_at": "2024-01-15",
    "source": null
  }
}

lago_id

string<uuid>

required

Unique identifier of the plan created by Lago.

Example:

"1a901a90-1a90-1a90-1a90-1a901a901a90"

name

string

required

The name of the plan.

Example:

"Startup"

created_at

string<date-time>

required

The date and time when the plan was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the plan was initially created.

Example:

"2023-06-27T19:43:42Z"

code

string

required

The code of the plan. It serves as a unique identifier associated with a particular plan. The code is typically used for internal or system-level identification purposes, like assigning a subscription, for instance.

Example:

"startup"

interval

enum<string>

required

The interval used for recurring billing. It represents the frequency at which subscription billing occurs. The interval can be one of the following values: yearly, semiannual, quarterly, monthly or weekly.

Available options:

weekly,

monthly,

quarterly,

semiannual,

yearly

Example:

"monthly"

amount_cents

integer

required

The base cost of the plan, excluding any applicable taxes, that is billed on a recurring basis. This value is defined at 0 if your plan is a pay-as-you-go plan.

Example:

10000

amount_currency

enum<string>

required

The currency of the plan. It indicates the monetary unit in which the plan's cost, including taxes and usage-based charges, is expressed.

Available options:

AED,

AFN,

ALL,

AMD,

ANG,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BWP,

BYN,

BZD,

CAD,

CDF,

CHF,

CLF,

CLP,

CNY,

COP,

CRC,

CVE,

CZK,

DJF,

DKK,

DOP,

DZD,

EGP,

ETB,

EUR,

FJD,

FKP,

GBP,

GEL,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

INR,

ISK,

JMD,

JPY,

KES,

KGS,

KHR,

KMF,

KRW,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

MAD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRO,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

NGN,

NIO,

NOK,

NPR,

NZD,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SEK,

SGD,

SHP,

SLL,

SOS,

SRD,

STD,

SZL,

THB,

TJS,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYU,

UZS,

VND,

VUV,

WST,

XAF,

XCD,

XOF,

XPF,

YER,

ZAR,

ZMW

Example:

"USD"

invoice_display_name

string

Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the plan will be used as the default display name.

Example:

"Startup plan"

description

string

The description on the plan.

Example:

""

trial_period

number

The duration in days during which the base cost of the plan is offered for free.

Example:

5

pay_in_advance

boolean

This field determines the billing timing for the plan. When set to true, the base cost of the plan is due at the beginning of each billing period. Conversely, when set to false, the base cost of the plan is due at the end of each billing period.

Example:

true

bill_charges_monthly

boolean | null

This field, when set to true, enables to invoice usage-based charges on monthly basis, even if the cadence of the plan is yearly or semiannual. This allows customers to pay charges overage on a monthly basis. This can be set to true only if the plan's interval is yearly or semiannual.

Example:

null

bill_fixed_charges_monthly

boolean | null

This field, when set to true, enables to invoice fixed charges on monthly basis, even if the cadence of the plan is yearly or semiannual. This allows customers to pay fixed charges on a monthly basis. This can be set to true only if the plan's interval is yearly or semiannual.

Example:

null

minimum_commitment

object | null

Show child attributes

charges

object[]

Additional usage-based charges for this plan.

Show child attributes

Example:

[
  {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a91",
    "lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a91",
    "billable_metric_code": "requests",
    "created_at": "2023-06-27T19:43:42Z",
    "charge_model": "package",
    "invoiceable": true,
    "invoice_display_name": "Setup",
    "pay_in_advance": false,
    "regroup_paid_fees": null,
    "prorated": false,
    "min_amount_cents": 3000,
    "properties": {
      "amount": "30",
      "free_units": 100,
      "package_size": 1000
    },
    "filters": []
  },
  {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a92",
    "lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a92",
    "billable_metric_code": "cpu",
    "created_at": "2023-06-27T19:43:42Z",
    "charge_model": "graduated",
    "invoiceable": true,
    "invoice_display_name": "Setup",
    "pay_in_advance": false,
    "regroup_paid_fees": null,
    "prorated": false,
    "min_amount_cents": 0,
    "properties": {
      "graduated_ranges": [
        {
          "from_value": 0,
          "to_value": 10,
          "flat_amount": "10",
          "per_unit_amount": "0.5"
        },
        {
          "from_value": 11,
          "to_value": null,
          "flat_amount": "0",
          "per_unit_amount": "0.4"
        }
      ]
    },
    "filters": []
  },
  {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a93",
    "lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a93",
    "billable_metric_code": "seats",
    "created_at": "2023-06-27T19:43:42Z",
    "charge_model": "standard",
    "invoiceable": true,
    "invoice_display_name": "Setup",
    "pay_in_advance": true,
    "regroup_paid_fees": null,
    "prorated": false,
    "min_amount_cents": 0,
    "properties": {},
    "filters": [
      {
        "invoice_display_name": "Europe",
        "properties": { "amount": "10" },
        "values": { "region": ["Europe"] }
      },
      {
        "invoice_display_name": "USA",
        "properties": { "amount": "5" },
        "values": { "region": ["USA"] }
      },
      {
        "invoice_display_name": "Africa",
        "properties": { "amount": "8" },
        "values": { "region": ["Africa"] }
      }
    ]
  },
  {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a94",
    "lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a94",
    "billable_metric_code": "storage",
    "created_at": "2023-06-27T19:43:42Z",
    "charge_model": "volume",
    "invoiceable": true,
    "invoice_display_name": "Setup",
    "pay_in_advance": false,
    "regroup_paid_fees": null,
    "prorated": false,
    "min_amount_cents": 0,
    "properties": {
      "volume_ranges": [
        {
          "from_value": 0,
          "to_value": 100,
          "flat_amount": "0",
          "per_unit_amount": "0"
        },
        {
          "from_value": 101,
          "to_value": null,
          "flat_amount": "0",
          "per_unit_amount": "0.5"
        }
      ]
    },
    "filters": []
  },
  {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a95",
    "lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a95",
    "billable_metric_code": "payments",
    "created_at": "2023-06-27T19:43:42Z",
    "charge_model": "percentage",
    "invoiceable": false,
    "invoice_display_name": "Setup",
    "pay_in_advance": true,
    "regroup_paid_fees": "invoice",
    "prorated": false,
    "min_amount_cents": 0,
    "properties": {
      "rate": "1",
      "fixed_amount": "0.5",
      "free_units_per_events": 5,
      "free_units_per_total_aggregation": "500"
    },
    "filters": []
  }
]

fixed_charges

object[]

List of fixed charges for this plan.

Show child attributes

Example:

[
  {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "lago_add_on_id": "2b802b80-2b80-2b80-2b80-2b802b802b80",
    "code": "setup_fee",
    "invoice_display_name": "Setup Fee",
    "add_on_code": "setup",
    "created_at": "2026-01-15T10:30:00Z",
    "charge_model": "standard",
    "pay_in_advance": true,
    "prorated": false,
    "properties": { "amount": "500" },
    "units": 1,
    "lago_parent_id": null,
    "taxes": [
      {
        "lago_id": "3c703c70-3c70-3c70-3c70-3c703c703c70",
        "name": "VAT",
        "code": "vat_20",
        "rate": 20,
        "description": "Standard VAT rate",
        "applied_to_organization": true,
        "created_at": "2026-01-01T00:00:00Z"
      }
    ]
  },
  {
    "lago_id": "4d604d60-4d60-4d60-4d60-4d604d604d60",
    "lago_add_on_id": "5e505e50-5e50-5e50-5e50-5e505e505e50",
    "code": "support_tier",
    "invoice_display_name": "Support Tier",
    "add_on_code": "premium_support",
    "created_at": "2026-01-15T10:30:00Z",
    "charge_model": "graduated",
    "pay_in_advance": false,
    "prorated": true,
    "properties": {
      "graduated_ranges": [
        {
          "from_value": 0,
          "to_value": 10,
          "per_unit_amount": "5",
          "flat_amount": "200"
        },
        {
          "from_value": 11,
          "to_value": null,
          "per_unit_amount": "1",
          "flat_amount": "300"
        }
      ]
    },
    "units": 1,
    "lago_parent_id": null,
    "taxes": []
  },
  {
    "lago_id": "6f406f40-6f40-6f40-6f40-6f406f406f40",
    "lago_add_on_id": "7a307a30-7a30-7a30-7a30-7a307a307a30",
    "code": "storage",
    "invoice_display_name": "Storage Allocation",
    "add_on_code": "cloud_storage",
    "created_at": "2026-01-15T10:30:00Z",
    "charge_model": "volume",
    "pay_in_advance": false,
    "prorated": false,
    "properties": {
      "volume_ranges": [
        {
          "from_value": 0,
          "to_value": 100,
          "per_unit_amount": "2",
          "flat_amount": "1"
        },
        {
          "from_value": 101,
          "to_value": null,
          "per_unit_amount": "1",
          "flat_amount": "0"
        }
      ]
    },
    "units": 50,
    "lago_parent_id": null,
    "taxes": []
  }
]

taxes

object[]

All taxes applied to the plan.

Show child attributes

usage_thresholds

object[]

List of usage thresholds applied to the plan.

Show child attributes

entitlements

object[]

List of all feature entitlements and their privileges available for this plan.

Show child attributes

metadata

object | null

Custom metadata stored as key-value pairs. Keys are strings (max 100 characters), values can be strings (max 255 characters) or null.

Show child attributes

Example:

{
  "external_id": "ext-123",
  "synced_at": "2024-01-15",
  "source": null
}