subscriptions

Override a charge for a subscription

Changed on Nov 3, 2026

This endpoint creates or updates a charge override for a specific subscription. If the subscription does not have a plan override yet, one will be created automatically. The charge override allows customizing specific charge properties (invoice_display_name, min_amount_cents, properties, filters, taxes, applied_pricing_unit) without affecting the original plan charge. This is a premium feature.

put/subscriptions/{external_id}/charges/{charge_code}

Request

Base URL
https://api.getlago.com/api/v1
Auth
HTTP bearer
TypeScript
https://skmtc.dev/getlago/apis/lago-api-documentation/docs/subscriptions/:external_id/charges/:charge_code/put.ts
A function with typed inputs. Its response is checked against the schema.

Query parameters

subscription_status'pending' | 'active' | 'terminated' | 'canceled' | 'incomplete'

Example:active

Filter by subscription status. When provided, the subscription is looked up with this status instead of the default active status. Possible values are pending, active, terminated, canceled, or incomplete.

Request body

Example request

{
  "charge": {
    "invoice_display_name": "Setup",
    "properties": {
      "grouped_by": [
        "agent_name"
      ],
      "pricing_group_keys": [
        "agent_name"
      ],
      "graduated_ranges": [
        {
          "to_value": 10,
          "flat_amount": "10",
          "per_unit_amount": "0.5"
        }
      ],
      "graduated_percentage_ranges": [
        {
          "to_value": 10,
          "rate": "1",
          "flat_amount": "10"
        }
      ],
      "amount": "30",
      "free_units": 100,
      "package_size": 1000,
      "rate": "1",
      "fixed_amount": "0.5",
      "free_units_per_events": 5,
      "free_units_per_total_aggregation": "500",
      "per_transaction_max_amount": "3.75",
      "per_transaction_min_amount": "1.75",
      "volume_ranges": [
        {
          "to_value": 10,
          "flat_amount": "10",
          "per_unit_amount": "0.5"
        }
      ],
      "presentation_group_keys": [
        {
          "value": "region",
          "options": {
            "display_in_invoice": true
          }
        }
      ]
    },
    "filters": [
      {
        "invoice_display_name": "AWS",
        "properties": {
          "grouped_by": [
            "agent_name"
          ],
          "pricing_group_keys": [
            "agent_name"
          ],
          "graduated_ranges": [
            {
              "to_value": 10,
              "flat_amount": "10",
              "per_unit_amount": "0.5"
            }
          ],
          "graduated_percentage_ranges": [
            {
              "to_value": 10,
              "rate": "1",
              "flat_amount": "10"
            }
          ],
          "amount": "30",
          "free_units": 100,
          "package_size": 1000,
          "rate": "1",
          "fixed_amount": "0.5",
          "free_units_per_events": 5,
          "free_units_per_total_aggregation": "500",
          "per_transaction_max_amount": "3.75",
          "per_transaction_min_amount": "1.75",
          "volume_ranges": [
            {
              "to_value": 10,
              "flat_amount": "10",
              "per_unit_amount": "0.5"
            }
          ]
        },
        "values": {
          "region": [
            "us-east-1"
          ]
        }
      }
    ],
    "tax_codes": [
      "french_standard_vat"
    ],
    "applied_pricing_unit": {
      "code": "credits",
      "conversion_rate": "0.5"
    }
  }
}

Response

Charge override created or updated

Example response

{
  "charge": {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "code": "api_requests_charge",
    "billable_metric_code": "requests",
    "invoice_display_name": "Setup",
    "created_at": "2022-09-14T16:35:31Z",
    "pay_in_advance": true,
    "invoiceable": true,
    "regroup_paid_fees": "invoice",
    "min_amount_cents": 1200,
    "properties": {
      "grouped_by": [
        "agent_name"
      ],
      "pricing_group_keys": [
        "agent_name"
      ],
      "graduated_ranges": [
        {
          "to_value": 10,
          "flat_amount": "10",
          "per_unit_amount": "0.5"
        }
      ],
      "graduated_percentage_ranges": [
        {
          "to_value": 10,
          "rate": "1",
          "flat_amount": "10"
        }
      ],
      "amount": "30",
      "free_units": 100,
      "package_size": 1000,
      "rate": "1",
      "fixed_amount": "0.5",
      "free_units_per_events": 5,
      "free_units_per_total_aggregation": "500",
      "per_transaction_max_amount": "3.75",
      "per_transaction_min_amount": "1.75",
      "volume_ranges": [
        {
          "to_value": 10,
          "flat_amount": "10",
          "per_unit_amount": "0.5"
        }
      ],
      "presentation_group_keys": [
        {
          "value": "region",
          "options": {
            "display_in_invoice": true
          }
        }
      ]
    },
    "filters": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "charge_code": "api_requests_charge",
        "invoice_display_name": "AWS",
        "properties": {
          "grouped_by": [
            "agent_name"
          ],
          "pricing_group_keys": [
            "agent_name"
          ],
          "graduated_ranges": [
            {
              "to_value": 10,
              "flat_amount": "10",
              "per_unit_amount": "0.5"
            }
          ],
          "graduated_percentage_ranges": [
            {
              "to_value": 10,
              "rate": "1",
              "flat_amount": "10"
            }
          ],
          "amount": "30",
          "free_units": 100,
          "package_size": 1000,
          "rate": "1",
          "fixed_amount": "0.5",
          "free_units_per_events": 5,
          "free_units_per_total_aggregation": "500",
          "per_transaction_max_amount": "3.75",
          "per_transaction_min_amount": "1.75",
          "volume_ranges": [
            {
              "to_value": 10,
              "flat_amount": "10",
              "per_unit_amount": "0.5"
            }
          ]
        },
        "values": {
          "region": [
            "us-east-1"
          ]
        }
      }
    ],
    "taxes": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "name": "TVA",
        "code": "french_standard_vat",
        "description": "French standard VAT",
        "rate": 20,
        "applied_to_organization": true,
        "applied_to_billing_entities_codes": [
          "acme_corp",
          "foo_bar"
        ],
        "created_at": "2023-07-06T14:35:58Z"
      }
    ],
    "applied_pricing_unit": {
      "code": "unit_code",
      "conversion_rate": "0.5"
    },
    "lago_parent_id": "1a901a90-1a90-1a90-1a90-1a901a901a90"
  }
}

Changes

Nov 3, 20265d26657495a3 Revision changes
- info
  added the new enum value incomplete to the query request parameter subscription_status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  the response property /// became required for the status

Operation history