> ## Documentation Index
> Fetch the complete documentation index at: https://lago-ftr-wallet-improvements.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# The plan object

> This object represents a plan. This plan can then be assigned to a customer.

<RequestExample>
  ```json The plan object
  {
    "plan": {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "name": "Startup",
      "invoice_display_name": "Startup plan",
      "created_at": "2023-06-27T19:43:42Z",
      "code": "startup",
      "interval": "monthly",
      "description": "",
      "amount_cents": 10000,
      "amount_currency": "USD",
      "trial_period": 5,
      "pay_in_advance": true,
      "bill_charges_monthly": null,
      "active_subscriptions_count": 0,
      "draft_invoices_count": 0,
      "minimum_commitment": {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "plan_code": "premium",
        "amount_cents": 100000,
        "invoice_display_name": "Minimum Commitment (C1)",
        "interval": "monthly",
        "created_at": "2022-04-29T08:59:51Z",
        "updated_at": "2022-04-29T08:59:51Z",
        "taxes": [
          {
            "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
            "name": "TVA",
            "code": "french_standard_vat",
            "description": "French standard VAT",
            "rate": 20,
            "applied_to_organization": true,
            "add_ons_count": 0,
            "charges_count": 0,
            "customers_count": 0,
            "plans_count": 0,
            "created_at": "2023-07-06T14:35:58Z"
          }
        ]
      },
      "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,
          "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,
          "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,
          "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,
          "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,
          "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": []
        }
      ],
      "taxes": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "name": "TVA",
          "code": "french_standard_vat",
          "description": "French standard VAT",
          "rate": 20,
          "applied_to_organization": true,
          "add_ons_count": 0,
          "charges_count": 0,
          "customers_count": 0,
          "plans_count": 0,
          "created_at": "2023-07-06T14:35:58Z"
        }
      ]
    }
  }
  ```
</RequestExample>

## Attributes

<ResponseField name="plan" type="object">
  <Expandable title="object" defaultOpen="true">
    <ResponseField name="lago_id" type="string" required>
      Unique identifier of the plan created by Lago.
    </ResponseField>

    <ResponseField name="created_at" type="string" 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.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      The name of the plan.
    </ResponseField>

    <ResponseField name="code" type="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.
    </ResponseField>

    <ResponseField name="interval" type="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: `weekly`, `monthly`, `quarterly` or `yearly`.
    </ResponseField>

    <ResponseField name="description" type="string">
      The description on the plan.
    </ResponseField>

    <ResponseField name="amount_cents" type="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.
    </ResponseField>

    <ResponseField name="amount_currency" type="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.
    </ResponseField>

    <ResponseField name="trial_period" type="float">
      The duration in days during which the base cost of the plan is offered for
      free.
    </ResponseField>

    <ResponseField name="pay_in_advance" type="boolean" required>
      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.
    </ResponseField>

    <ResponseField name="bill_charges_monthly" type="boolean">
      This field, when set to `true`, enables to invoice usage-based charges on
      monthly basis, even if the cadence of the plan is `yearly`. 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`.
    </ResponseField>

    <ResponseField name="tax_code" type="string">
      List of unique code used to identify the taxes.
    </ResponseField>

    <ResponseField name="invoice_display_name" type="string">
      Specifies the name that will be displayed on an invoice. If no value is
      set for this field, the name of the actual charge will be used as the
      default display name.
    </ResponseField>

    <ResponseField name="active_subscriptions_count" type="integer" required>
      The count of active subscriptions that are currently associated with the
      plan. This field provides valuable information regarding the impact of
      deleting the plan. By checking the value of this field, you can determine
      the number of subscriptions that will be affected if the plan is deleted.
    </ResponseField>

    <ResponseField name="draft_invoices_count" type="integer" required>
      The number of draft invoices that include a subscription attached to the
      plan. This field provides valuable information about the impact of
      deleting the plan. By checking the value of this field, you can determine
      the number of draft invoices that will be affected if the plan is deleted.
    </ResponseField>

    <ResponseField name="draft_invoices_count" type="integer" required>
      The number of draft invoices that include a subscription attached to the
      plan. This field provides valuable information about the impact of
      deleting the plan. By checking the value of this field, you can determine
      the number of draft invoices that will be affected if the plan is deleted.
    </ResponseField>

    <ResponseField name="minimum_commitment" type="object">
      <Expandable title="minimum_commitment">
        <ResponseField name="lago_id" type="string" required>
          Unique identifier of charge, created by Lago.
        </ResponseField>

        <ResponseField name="plan_code" type="string">
          The unique code representing the plan to be attached to the customer.
        </ResponseField>

        <ResponseField name="amount_cents" type="integer" required>
          The amount of the minimum commitment in cents.
        </ResponseField>

        <ResponseField name="invoice_display_name" type="string">
          Specifies the name that will be displayed on an invoice. If no value
          is set for this field, the default name will be used as the display
          name.
        </ResponseField>

        <ResponseField name="interval" type="string">
          The interval used for recurring billing. It represents the frequency
          at which minimum commitment billing occurs. Available options:
          `weekly`, `monthly`, `quarterly`, `yearly`.
        </ResponseField>

        <ResponseField name="created_at" type="string" required>
          The date and time when the minimum commitment 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
          minimum commitment was initially created..
        </ResponseField>

        <ResponseField name="updated_at" type="string">
          The date and time when the minimum commitment was updated. It is
          expressed in UTC format according to the ISO 8601 datetime standard.
          This field provides the timestamp for the exact moment when the
          minimum commitment was initially created.
        </ResponseField>

        <ResponseField name="taxes" type="object[]">
          All taxes applied to the minimum commitment.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="charges" type="array">
      <Expandable title="charges">
        <ResponseField name="lago_id" type="string" required>
          Unique identifier of the minimum commitment, created by Lago.
        </ResponseField>

        <ResponseField name="lago_billable_metric_id" type="string" required>
          Unique identifier of the billable metric created by Lago.
        </ResponseField>

        <ResponseField name="billable_metric_code" type="string" required>
          Unique code identifying a billable metric.
        </ResponseField>

        <ResponseField name="created_at" type="string" required>
          The date and time when the charge was created. It is expressed in UTC
          format according to the ISO 8601 datetime standard.
        </ResponseField>

        <ResponseField name="charge_model" type="string" required>
          Specifies the pricing model used for the calculation of the final fee.
          It can be `standard`, `graduated`, `package`, `percentage`, or
          `volume`.
        </ResponseField>

        <ResponseField name="pay_in_advance" type="boolean">
          This field determines the billing timing for this specific usage-based
          charge. When set to `true`, the charge is due and invoiced
          immediately. Conversely, when set to `false`, the charge is due and
          invoiced at the end of each billing period.
        </ResponseField>

        <ResponseField name="invoiceable" type="boolean">
          This field specifies whether the charge should be included in a proper
          invoice. If set to `false`, no invoice will be issued for this charge.
          You can only set it to `false` when `pay_in_advance` is `true`.
        </ResponseField>

        <ResponseField name="min_amount_cents" type="integer">
          The minimum spending amount required for the charge, measured in cents
          and excluding any applicable taxes. It indicates the minimum amount
          that needs to be charged for each billing period.
        </ResponseField>

        <ResponseField name="invoice_display_name" type="string">
          Specifies the name that will be displayed on an invoice. If no value
          is set for this field, the name of the actual charge will be used as
          the default display name.
        </ResponseField>

        <ResponseField name="prorated" type="boolean" required>
          Specifies whether a charge is prorated based on the remaining number
          of days in the billing period or billed fully. If not defined, this
          argument is set to `false` by default. - If set to `true`, the charge
          is prorated based on the remaining days in the current billing period.

          * If set to `false`, the charge is billed in full. Note that only a
            `charge_model` sets to `standard`, `graduated` and `volume` can be
            prorated.
        </ResponseField>

        <ResponseField name="tax_code" type="string">
          List of unique code used to identify the taxes.
        </ResponseField>

        <ResponseField name="properties" type="JSON">
          <Expandable>
            ### Case of groups and dimensions

            <ResponseField name="group_properties" type="array">
              <Expandable>
                <ResponseField name="invoice_display_name" type="string">
                  Specifies the name that will be displayed on an invoice. If no
                  value is set for this field, the values of the filter will be
                  used as the default display name.
                </ResponseField>

                <ResponseField name="values" type="string">
                  List of possible filter values. The key and values must match
                  one of the billable metric filters.
                </ResponseField>
              </Expandable>
            </ResponseField>

            ### Case of graduated pricing model

            <ResponseField name="graduated_ranges" type="array" required>
              <Expandable>
                <ResponseField name="from_value" type="integer" required>
                  Specifies the lower value of a tier for a `graduated` charge
                  model. It must be either 0 or the previous range's `to_value +
                                                      1` to maintain the proper sequence of values.
                </ResponseField>

                <ResponseField name="to_value" type="integer" required>
                  Specifies the highest value of a tier for a `graduated` charge
                  model. - This value must be higher than the `from_value` of
                  the same tier. - This value must be `null` for the last tier.
                </ResponseField>

                <ResponseField name="per_unit_amount" type="string" required>
                  The unit price, excluding tax, for a specific tier of a
                  `graduated` charge model. It is expressed as a decimal value.
                </ResponseField>

                <ResponseField name="flat_amount" type="string" required>
                  The flat amount for a whole tier, excluding tax, for a
                  `graduated` charge model. It is expressed as a decimal value.
                </ResponseField>
              </Expandable>
            </ResponseField>

            ### Case of package pricing model

            <ResponseField name="amount" type="string" required>
              The amount, excluding tax, for a complete set of units in a
              `package` charge model. It is expressed as a decimal value.
            </ResponseField>

            <ResponseField name="package_size" type="integer" required>
              The quantity of units included in each pack or set for a `package`
              charge model. It indicates the number of units that are bundled
              together as a single package or set within the pricing structure.
            </ResponseField>

            <ResponseField name="free_units" type="integer" required>
              The quantity of units that are provided free of charge for each
              billing period in a `package` charge model. This field specifies
              the number of units that customers can use without incurring any
              additional cost during each billing cycle.
            </ResponseField>

            ### Case of percentage pricing model

            <ResponseField name="rate" type="string" required>
              The percentage rate that is applied to the amount of each
              transaction for a `percentage` charge model. It is expressed as a
              decimal value.
            </ResponseField>

            <ResponseField name="fixed_amount" type="string">
              The fixed fee that is applied to each transaction for a
              `percentage` charge model. It is expressed as a decimal value.
            </ResponseField>

            <ResponseField name="free_units_per_events" type="integer">
              The count of transactions that are not impacted by the
              `percentage` rate and fixed fee in a percentage charge model. This
              field indicates the number of transactions that are exempt from
              the calculation of charges based on the specified percentage rate
              and fixed fee.
            </ResponseField>

            <ResponseField name="free_units_per_total_aggregation" type="integer">
              The transaction amount that is not impacted by the `percentage`
              rate and fixed fee in a percentage charge model. This field
              indicates the portion of the transaction amount that is exempt
              from the calculation of charges based on the specified percentage
              rate and fixed fee.
            </ResponseField>

            <ResponseField name="per_transaction_min_amount" type="string">
              Specifies the minimum allowable spending for a single transaction.
              Working as a transaction floor. Cannot be greater than the
              `per_transaction_max_amount` value.
            </ResponseField>

            <ResponseField name="per_transaction_max_amount" type="string">
              Specifies the maximum allowable spending for a single transaction.
              Working as a transaction cap. Cannot be lower than the
              `per_transaction_min_amount` value.
            </ResponseField>

            ### Case of volume pricing model

            <ResponseField name="volume_ranges" type="array" required>
              <Expandable>
                <ResponseField name="from_value" type="integer" required>
                  Specifies the lower value of a tier for a `volume` charge
                  model. It must be either 0 or the previous range's to\_value +
                  1 to maintain the proper sequence of values.
                </ResponseField>

                <ResponseField name="to_value" type="integer" required>
                  Specifies the highest value of a tier for a `volume` charge
                  model. - This value must be higher than the `from_value` of
                  the same tier. - This value must be `null` for the last tier.
                </ResponseField>

                <ResponseField name="per_unit_amount" type="string" required>
                  The unit price, excluding tax, for a specific tier of a
                  `volume` charge model. It is expressed as a decimal value.
                </ResponseField>

                <ResponseField name="flat_amount" type="string" required>
                  The flat amount for a whole tier, excluding tax, for a
                  `volume` charge model. It is expressed as a decimal value.
                </ResponseField>
              </Expandable>
            </ResponseField>

            ### Case of graduated percentage pricing model

            <ResponseField name="graduated_percentage_ranges" type="array" required>
              <Expandable>
                <ResponseField name="from_value" type="integer" required>
                  Specifies the lower value of a tier for a `graduated
                                                      percentage` charge model. It must be either 0 or the previous
                  range's to\_value + 1 to maintain the proper sequence of
                  values.
                </ResponseField>

                <ResponseField name="to_value" type="integer" required>
                  Specifies the highest value of a tier for a `graduated
                                                      percentage` charge model. - This value must be higher than the
                  `from_value` of the same tier. - This value must be `null` for
                  the last tier.
                </ResponseField>

                <ResponseField name="rate" type="string" required>
                  The percentage rate that is applied to the amount of each
                  transaction for a `graduated percentage` charge model. It is
                  expressed as a decimal value, and only set for a specific
                  tier.
                </ResponseField>

                <ResponseField name="flat_amount" type="string" required>
                  The flat amount for a whole tier, excluding tax, for a
                  `graduated percentage` charge model. It is expressed as a
                  decimal value.
                </ResponseField>
              </Expandable>
            </ResponseField>

            ### Case of standard pricing model

            <ResponseField name="amount" type="string" required>
              The unit price, excluding tax, for a `standard` charge model. It
              is expressed as a decimal value.
            </ResponseField>

            <ResponseField name="grouped_by" type="array">
              The list of event properties that are used to group the events on
              the invoice for a `standard` charge model.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>