> ## 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 fee object

> This object represents a line item of an invoice, handling amount, billed units and item description.

<RequestExample>
  ```json The fee object
  {
    "fee": {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "lago_charge_filter_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "lago_invoice_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "lago_true_up_fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "lago_true_up_parent_fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "lago_subscription_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "lago_customer_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "external_customer_id": "external_id",
      "external_subscription_id": "external_id",
      "invoice_display_name": "Setup Fee (SF1)",
      "amount_cents": 100,
      "amount_currency": "EUR",
      "taxes_amount_cents": 20,
      "taxes_rate": 20,
      "units": "0.32",
      "precise_unit_amount": "312.5",
      "total_amount_cents": 120,
      "total_amount_currency": "EUR",
      "events_count": 23,
      "pay_in_advance": true,
      "invoiceable": true,
      "from_date": "2022-04-29T08:59:51Z",
      "to_date": "2022-05-29T08:59:51Z",
      "payment_status": "pending",
      "created_at": "2022-08-24T14:58:59Z",
      "succeeded_at": "2022-08-24T14:58:59Z",
      "failed_at": "2022-08-24T14:58:59Z",
      "refunded_at": "2022-08-24T14:58:59Z",
      "event_transaction_id": "transaction_1234567890",
      "amount_details": {
        "graduated_ranges": [
          {
            "units": "10.0",
            "from_value": 0,
            "to_value": 10,
            "flat_unit_amount": "1.0",
            "per_unit_amount": "1.0",
            "per_unit_total_amount": "10.0",
            "total_with_flat_amount": "11.0"
          }
        ],
        "graduated_percentage_ranges": [
          {
            "units": "10.0",
            "from_value": 0,
            "to_value": 10,
            "flat_unit_amount": "1.0",
            "rate": "1.0",
            "per_unit_total_amount": "10.0",
            "total_with_flat_amount": "11.0"
          }
        ],
        "free_units": "10.0",
        "paid_units": "40.0",
        "per_package_size": 1000,
        "per_package_unit_amount": "0.5",
        "units": "20.0",
        "free_events": 10,
        "rate": "1.0",
        "per_unit_total_amount": "10.0",
        "paid_events": 20,
        "fixed_fee_unit_amount": "1.0",
        "fixed_fee_total_amount": "20.0",
        "min_max_adjustment_total_amount": "20.0",
        "volume_ranges": [
          {
            "per_unit_amount": "0.5",
            "flat_unit_amount": "10.0",
            "per_unit_total_amount": "10.0"
          }
        ]
      },
      "item": {
        "type": "subscription",
        "code": "startup",
        "name": "Startup",
        "invoice_display_name": "Setup Fee (SF1)",
        "filter_invoice_display_name": "AWS eu-east-1",
        "filters": {
          "additionalProp1": [
            "string"
          ],
          "additionalProp2": [
            "string"
          ],
          "additionalProp3": [
            "string"
          ]
        },
        "lago_item_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "item_type": "Subscription",
        "grouped_by": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        }
      },
      "applied_taxes": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "lago_tax_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "tax_name": "TVA",
          "tax_code": "french_standard_vat",
          "tax_rate": 20,
          "tax_description": "French standard VAT",
          "amount_cents": 2000,
          "amount_currency": "USD",
          "created_at": "2022-09-14T16:35:31Z",
          "lago_fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a90"
        }
      ]
    }
  }
  ```
</RequestExample>

## Attributes

<ResponseField name="fee" type="object">
  <Expandable title="object" defaultOpen="true">
    <ResponseField name="lago_id" type="string" required>
      Unique identifier assigned to the fee within the Lago application. This ID
      is exclusively created by Lago and serves as a unique identifier for the
      fee’s record within the Lago system.
    </ResponseField>

    <ResponseField name="lago_group_id" type="string">
      Unique identifier assigned to the group that the fee belongs to
    </ResponseField>

    <ResponseField name="lago_invoice_id" type="string">
      Unique identifier assigned to the invoice that the fee belongs to
    </ResponseField>

    <ResponseField name="lago_true_up_fee_id" type="string">
      Unique identifier assigned to the true-up fee when a minimum has been set
      to the charge. This identifier helps to distinguish and manage the true-up
      fee associated with the charge, which may be applicable when a minimum
      threshold or limit is set for the charge amount.
    </ResponseField>

    <ResponseField name="lago_true_up_parent_fee_id" type="string">
      Unique identifier assigned to the parent fee on which the true-up fee is
      assigned. This identifier establishes the relationship between the parent
      fee and the associated true-up fee.
    </ResponseField>

    <ResponseField name="lago_subscription_id" type="string">
      Unique identifier assigned to the subscription, created by Lago. This
      field is specifically displayed when the fee type is charge or
      subscription.
    </ResponseField>

    <ResponseField name="lago_customer_id" type="string">
      Unique identifier assigned to the customer in your application. This field
      is specifically displayed when the fee type is charge or subscription.
    </ResponseField>

    ro

    <ResponseField name="external_customer_id" type="string">
      Unique identifier assigned to the customer in your application. This field
      is specifically displayed when the fee type is charge or subscription.
    </ResponseField>

    <ResponseField name="external_subscription_id" type="string">
      Unique identifier assigned to the subscription in your application. This
      field is specifically displayed when the fee type is charge or
      subscription.
    </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="amount_cents" type="integer" required>
      The cost of this specific fee, excluding any applicable taxes.
    </ResponseField>

    <ResponseField name="amount_currency" type="string" required>
      The currency of this specific fee. It indicates the monetary unit in which
      the fee's cost is expressed.

      <Expandable title="Enum">
        \[`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`, `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`]
      </Expandable>
    </ResponseField>

    <ResponseField name="taxes_amount_cents" type="integer" required>
      The cost of the tax associated with this specific fee.
    </ResponseField>

    <ResponseField name="taxes_rate" type="number" required>
      The tax rate associated with this specific fee.
    </ResponseField>

    <ResponseField name="units" type="string" required>
      The number of units used to charge the customer. This field indicates the
      quantity or count of units consumed or utilized in the context of the
      charge. It helps in determining the basis for calculating the fee or cost
      associated with the usage of the service or product provided to the
      customer.
    </ResponseField>

    <ResponseField name="precise_unit_amount" type="string" required>
      The unit amount of the fee per unit, with precision.
    </ResponseField>

    <ResponseField name="total_amount_cents" type="integer" required>
      The cost of this specific fee, including any applicable taxes.
    </ResponseField>

    <ResponseField name="total_amount_currency" type="string" required>
      The currency of this specific fee, including any applicable taxes.

      <Expandable title="Enum">
        \[`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`, `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`]
      </Expandable>
    </ResponseField>

    <ResponseField name="events_count" type="integer">
      The number of events that have been sent and used to charge the customer.
      This field indicates the count or quantity of events that have been
      processed and considered in the charging process.
    </ResponseField>

    <ResponseField name="pay_in_advance" type="boolean" required>
      Flag that indicates whether the fee was paid in advance. It serves as a
      boolean value, where `true` represents that the fee was paid in advance
      (straightaway), and `false` indicates that the fee was not paid in arrears
      (at the end of the period).
    </ResponseField>

    <ResponseField name="invoiceable" type="boolean" required>
      Flag that indicates whether the fee was included on the invoice. It serves
      as a boolean value, where `true` represents that the fee was included on
      the invoice, and `false` indicates that the fee was not included on the
      invoice.
    </ResponseField>

    <ResponseField name="from_date" type="string">
      The beginning date of the period that the fee covers. It is applicable
      only to `subscription` and `charge` fees. This field indicates the start
      date of the billing period or subscription period associated with the fee.
    </ResponseField>

    <ResponseField name="to_date" type="string">
      The ending date of the period that the fee covers. It is applicable only
      to `subscription` and `charge` fees. This field indicates the end date of
      the billing period or subscription period associated with the fee.
    </ResponseField>

    <ResponseField name="payment_status" type="string" required>
      Indicates the payment status of the fee. It represents the current status
      of the payment associated with the fee. The possible values for this field
      are `pending`, `succeeded`, `failed`, and `refunded`.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      The date and time when the fee was created. It is provided in Coordinated
      Universal Time (UTC) format.
    </ResponseField>

    <ResponseField name="succeeded_at" type="string">
      The date and time when the payment for the fee was successfully processed.
      It is provided in Coordinated Universal Time (UTC) format.
    </ResponseField>

    <ResponseField name="failed_at" type="string">
      The date and time when the payment for the fee failed to process. It is
      provided in Coordinated Universal Time (UTC) format.
    </ResponseField>

    <ResponseField name="refunded_at" type="string">
      The date and time when the payment for the fee was refunded. It is
      provided in Coordinated Universal Time (UTC) format
    </ResponseField>

    <ResponseField name="event_transaction_id" type="string">
      Unique identifier assigned to the transaction. This field is specifically
      displayed when the fee type is `charge` and the payment for the fee is
      made in advance (`pay_in_advance` is set to `true`).
    </ResponseField>

    <ResponseField name="amount_details" type="object" required>
      List of all unit amount details for calculating the fee.

      <Expandable>
        ### Case of a fee linked to a graduated charge model

        <ResponseField name="graduated_ranges" type="array">
          Graduated ranges, used for a `graduated` charge model.

          <Expandable>
            <ResponseField name="units" type="string">
              Total units received in Lago.
            </ResponseField>

            <ResponseField name="from_value" type="integer">
              Lower value of a tier. It is either 0 or the previous range's
              `to_value` + 1
            </ResponseField>

            <ResponseField name="to_value" type="integer">
              Highest value of a tier. - This value is higher than the
              from\_value of the same tier. - This value is null for the last
              tier.
            </ResponseField>

            <ResponseField name="flat_unit_amount" type="string">
              Flat unit amount within a specified tier.
            </ResponseField>

            <ResponseField name="per_unit_amount" type="string">
              Amount per unit within a specified tier.
            </ResponseField>

            <ResponseField name="per_unit_total_amount" type="string">
              Total amount of received units to be charged within a specified
              tier.
            </ResponseField>

            <ResponseField name="total_with_flat_amount" type="string">
              Total amount to be charged for a specific tier, taking into
              account the `flat_unit_amount` and the `per_unit_total_amount`.
            </ResponseField>
          </Expandable>
        </ResponseField>

        ### Case of a fee linked to a graduated percentage charge model

        <ResponseField name="graduated_percentage_ranges" type="array">
          Graduated percentage ranges, used for a `graduated_percentage` charge
          model.

          <Expandable>
            <ResponseField name="units" type="string">
              Total units received in Lago.
            </ResponseField>

            <ResponseField name="from_value" type="integer">
              Lower value of a tier. It is either 0 or the previous range's
              `to_value` + 1
            </ResponseField>

            <ResponseField name="to_value" type="integer">
              Highest value of a tier. - This value is higher than the
              from\_value of the same tier. - This value is null for the last
              tier.
            </ResponseField>

            <ResponseField name="flat_unit_amount" type="string">
              Flat unit amount within a specified tier.
            </ResponseField>

            <ResponseField name="rate" type="string">
              Percentage rate applied within a specified tier.
            </ResponseField>

            <ResponseField name="per_unit_total_amount" type="string">
              Total amount of received units to be charged within a specified
              tier.
            </ResponseField>

            <ResponseField name="total_with_flat_amount" type="string">
              Total amount to be charged for a specific tier, taking into
              account the `flat_unit_amount` and the `per_unit_total_amount`.
            </ResponseField>
          </Expandable>
        </ResponseField>

        ### Case of a fee linked to a package charge model

        <ResponseField name="free_units" type="string">
          The quantity of units that are provided free of charge for each
          billing period in a `package` charge model.
        </ResponseField>

        <ResponseField name="paid_units" type="string">
          The quantity of units that are not provided free of charge for each
          billing period in a `package` charge model.
        </ResponseField>

        <ResponseField name="per_package_size" type="integer">
          The quantity of units included, defined for `package` or `percentage`
          charge model.
        </ResponseField>

        <ResponseField name="per_package_unit_amount" type="string">
          Total amount to charge for received `paid_units``, defined for
                              `package`or`percentage\` charge model.
        </ResponseField>

        ### Case of a fee linked to a percentage charge model

        <ResponseField name="units" type="string">
          The total units received in Lago for the `percentage` charge model.
        </ResponseField>

        <ResponseField name="free_events" type="integer">
          Total number of free events allowed for the `percentage` charge model.
        </ResponseField>

        <ResponseField name="free_units" type="string">
          The quantity of units that are provided free of charge for each
          billing period in a `package` or `percentage` charge model.
        </ResponseField>

        <ResponseField name="paid_units" type="string">
          The quantity of units that are not provided free of charge for each
          billing period in a `package` or `percentage` charge model.
        </ResponseField>

        <ResponseField name="rate" type="string">
          Percentage rate applied for the Percentage charge model.
        </ResponseField>

        <ResponseField name="per_unit_total_amount" type="string">
          Total amount of received units to be charged for the `percentage`
          charge model.
        </ResponseField>

        <ResponseField name="paid_events" type="integer">
          Total number of paid events for the `percentage` charge model.
        </ResponseField>

        <ResponseField name="fixed_fee_unit_amount" type="string">
          Fixed fee unit price per received paid\_event for the `percentage`
          charge model.
        </ResponseField>

        <ResponseField name="fixed_fee_total_amount" type="string">
          Total amount to charge for received paid\_events for the `percentage`
          charge model.
        </ResponseField>

        <ResponseField name="min_max_adjustment_total_amount" type="string">
          Total adjustment amount linked to minimum and maximum spending per
          transaction for the `percentage` charge model.
        </ResponseField>

        ### Case of a fee linked to a volume charge model

        <ResponseField name="volume_ranges" type="array">
          Volumes ranges, used for a `volume` charge model.

          <Expandable>
            <ResponseField name="flat_unit_amount" type="string">
              The unit price, excluding tax, for a specific tier of a `volume`
              charge model.
            </ResponseField>

            <ResponseField name="per_unit_amount" type="string">
              The flat amount for a whole tier, excluding tax, for a `volume`
              charge model.
            </ResponseField>

            <ResponseField name="per_unit_total_amount" type="string">
              Total amount of received units to be charged.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="item" type="object">
      <Expandable title="item">
        <ResponseField name="type" type="string" required>
          The fee type. Possible values are `add-on`, `charge`, `credit` or
          `subscription`.
        </ResponseField>

        <ResponseField name="code" type="string" required>
          The code of the fee item. It can be the code of the `add-on`, the code
          of the `charge`, the code of the `credit` or the code of the
          `subscription`.
        </ResponseField>

        <ResponseField name="name" type="string" required>
          The name of the fee item. It can be the name of the `add-on`, the name
          of the `charge`, the name of the `credit` or the name of the
          `subscription`.
        </ResponseField>

        <ResponseField name="lago_item_id" type="string" required>
          Unique identifier of the fee item, created by Lago. It can be the
          identifier of the add-on, the identifier of the `charge`, the
          identifier of the `credit` or the identifier of the `subscription`.
        </ResponseField>

        <ResponseField name="item_type" type="string" required>
          The type of the fee item. Possible values are `AddOn`,
          `BillableMetric`, `WalletTransaction` or `Subscription`.
        </ResponseField>

        <ResponseField name="grouped_by" type="string" required>
          Key value list of event properties aggregated by the charge model.
        </ResponseField>

        <ResponseField name="filters" type="string" required>
          Key value list of event properties.
        </ResponseField>

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

    <ResponseField name="applied_taxes" type="object">
      <Expandable title="applied_taxes">
        <ResponseField name="lago_id" type="string" required>
          Unique identifier of the applied tax, created by Lago.
        </ResponseField>

        <ResponseField name="lago_tax_id" type="string" required>
          Unique identifier of the tax, created by Lago.
        </ResponseField>

        <ResponseField name="tax_name" type="string" required>
          Name of the tax.
        </ResponseField>

        <ResponseField name="tax_code" type="string" required>
          Unique code used to identify the tax associated with the API request.
        </ResponseField>

        <ResponseField name="tax_rate" type="number" required>
          The rate of the tax.
        </ResponseField>

        <ResponseField name="tax_description" type="string">
          Internal description of the tax.
        </ResponseField>

        <ResponseField name="amount_cents" type="integer" required>
          Amount of the tax.
        </ResponseField>

        <ResponseField name="amount_currency" type="string" required>
          The currency of the tax.
        </ResponseField>

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

        <ResponseField name="lago_fee_id" type="string" required>
          Unique identifier of the fee, created by Lago.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>