From e6a4abd0339c667f0adde6328abf3ab564f894ca Mon Sep 17 00:00:00 2001 From: "lago-claude-ai-agent[bot]" <297187938+lago-claude-ai-agent[bot]@users.noreply.github.com> Date: Mon, 28 Sep 2026 08:06:49 +0000 Subject: [PATCH 1/4] fix: correct typos and definitions (guardian sweep) - "evalutated" -> "evaluated" and "Accepted function are" -> "Accepted functions are" on the billable-metric expression descriptions - "miliseconds" -> "milliseconds" on the event input timestamp Co-Authored-By: Claude Opus 5 (1M context) --- openapi.yaml | 10 +++++----- src/schemas/BillableMetricBaseInput.yaml | 4 ++-- src/schemas/BillableMetricEvaluateExpressionInput.yaml | 4 ++-- src/schemas/EventInputObject.yaml | 2 +- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 3b89551c..fc123f52 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -13627,8 +13627,8 @@ components: - 'null' example: round((ended_at - started_at) * units) description: | - Expression used to calculate the event units. The expression is evalutated for each event and the result is then used to calculate the total aggregated units. - Accepted function are `ceil`, `concat` and `round` as well as `+`, `-`, `\` and `*` operations. + Expression used to calculate the event units. The expression is evaluated for each event and the result is then used to calculate the total aggregated units. + Accepted functions are `ceil`, `concat` and `round` as well as `+`, `-`, `\` and `*` operations. Round is accepting an optional second parameter to specify the number of decimal. rounding_function: type: @@ -13705,8 +13705,8 @@ components: type: string example: round((ended_at - started_at) * units) description: | - Expression used to calculate the event units. The expression is evalutated for each event and the result is then used to calculate the total aggregated units. - Accepted function are `ceil`, `concat` and `round` as well as `+`, `-`, `\` and `*` operations. + Expression used to calculate the event units. The expression is evaluated for each event and the result is then used to calculate the total aggregated units. + Accepted functions are `ceil`, `concat` and `round` as well as `+`, `-`, `\` and `*` operations. Round is accepting an optional second parameter to specify the number of decimal. event: type: object @@ -19326,7 +19326,7 @@ components: description: | This field captures the Unix timestamp in seconds indicating the occurrence of the event in Coordinated Universal Time (UTC). If this timestamp is not provided, the API will automatically set it to the time of event reception. - You can also provide miliseconds precision by appending decimals to the timestamp. + You can also provide milliseconds precision by appending decimals to the timestamp. precise_total_amount_cents: type: - string diff --git a/src/schemas/BillableMetricBaseInput.yaml b/src/schemas/BillableMetricBaseInput.yaml index 0acf95c0..e8245735 100644 --- a/src/schemas/BillableMetricBaseInput.yaml +++ b/src/schemas/BillableMetricBaseInput.yaml @@ -29,8 +29,8 @@ properties: - "null" example: "round((ended_at - started_at) * units)" description: | - Expression used to calculate the event units. The expression is evalutated for each event and the result is then used to calculate the total aggregated units. - Accepted function are `ceil`, `concat` and `round` as well as `+`, `-`, `\` and `*` operations. + Expression used to calculate the event units. The expression is evaluated for each event and the result is then used to calculate the total aggregated units. + Accepted functions are `ceil`, `concat` and `round` as well as `+`, `-`, `\` and `*` operations. Round is accepting an optional second parameter to specify the number of decimal. rounding_function: type: diff --git a/src/schemas/BillableMetricEvaluateExpressionInput.yaml b/src/schemas/BillableMetricEvaluateExpressionInput.yaml index 107eec59..0ad7ee80 100644 --- a/src/schemas/BillableMetricEvaluateExpressionInput.yaml +++ b/src/schemas/BillableMetricEvaluateExpressionInput.yaml @@ -7,8 +7,8 @@ properties: type: string example: "round((ended_at - started_at) * units)" description: | - Expression used to calculate the event units. The expression is evalutated for each event and the result is then used to calculate the total aggregated units. - Accepted function are `ceil`, `concat` and `round` as well as `+`, `-`, `\` and `*` operations. + Expression used to calculate the event units. The expression is evaluated for each event and the result is then used to calculate the total aggregated units. + Accepted functions are `ceil`, `concat` and `round` as well as `+`, `-`, `\` and `*` operations. Round is accepting an optional second parameter to specify the number of decimal. event: type: object diff --git a/src/schemas/EventInputObject.yaml b/src/schemas/EventInputObject.yaml index fa19f08e..049f378a 100644 --- a/src/schemas/EventInputObject.yaml +++ b/src/schemas/EventInputObject.yaml @@ -30,7 +30,7 @@ properties: description: | This field captures the Unix timestamp in seconds indicating the occurrence of the event in Coordinated Universal Time (UTC). If this timestamp is not provided, the API will automatically set it to the time of event reception. - You can also provide miliseconds precision by appending decimals to the timestamp. + You can also provide milliseconds precision by appending decimals to the timestamp. precise_total_amount_cents: type: - string From 7db4ab8b57f7751084dd0ff4109850780af7bb40 Mon Sep 17 00:00:00 2001 From: "lago-claude-ai-agent[bot]" <297187938+lago-claude-ai-agent[bot]@users.noreply.github.com> Date: Mon, 28 Sep 2026 08:07:23 +0000 Subject: [PATCH 2/4] fix: correct filters and query params in events timestamp_from_started_at cannot be combined with timestamp_from: Queries::EventsQueryFiltersContract fails the request with "cannot be used with timestamp_from_started_at" when both are sent. Co-Authored-By: Claude Opus 5 (1M context) --- openapi.yaml | 2 +- src/resources/events.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index fc123f52..55b2f9d3 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -3343,7 +3343,7 @@ paths: example: event-123 - name: timestamp_from_started_at in: query - description: Requires `external_subscription_id` to be set. Filter events by timestamp after the subscription started at datetime. + description: Requires `external_subscription_id` to be set, and cannot be combined with `timestamp_from`. Filter events by timestamp after the subscription started at datetime. required: false explode: true schema: diff --git a/src/resources/events.yaml b/src/resources/events.yaml index 6dd7a1aa..7680607d 100644 --- a/src/resources/events.yaml +++ b/src/resources/events.yaml @@ -47,7 +47,7 @@ get: example: "event-123" - name: timestamp_from_started_at in: query - description: Requires `external_subscription_id` to be set. Filter events by timestamp after the subscription started at datetime. + description: Requires `external_subscription_id` to be set, and cannot be combined with `timestamp_from`. Filter events by timestamp after the subscription started at datetime. required: false explode: true schema: From 760890d20b5c21862a31c40c1f9752b3716110d9 Mon Sep 17 00:00:00 2001 From: "lago-claude-ai-agent[bot]" <297187938+lago-claude-ai-agent[bot]@users.noreply.github.com> Date: Mon, 28 Sep 2026 08:08:00 +0000 Subject: [PATCH 3/4] fix: align billable_metrics and events schemas with lago-api BillableMetricObject: - aggregation_type gains custom_agg. BillableMetric::AGGREGATION_TYPES maps custom_agg to 7 and V1::BillableMetricSerializer emits the enum name verbatim, so the API can return a value the spec rejected. custom_aggregator is never assigned from a permitted param, so the value is read-only over the API; the description says so. - expression becomes nullable. db/structure.sql declares it "expression character varying" with no NOT NULL, and the serializer emits the column unconditionally. EventObject: - timestamp described as an ISO 8601 datetime, not a Unix timestamp in seconds: V1::EventSerializer emits model.timestamp.iso8601(3). The Unix-seconds form is the request format, already documented on EventInputObject. - external_subscription_id no longer refers to external_customer_id, which Api::V1::EventsController#create_params does not permit. EventEstimateFeesInput: - document precise_total_amount_cents. estimate_fees runs on create_params, which permits it, and Fees::EstimatePayInAdvanceService reads event_params[:precise_total_amount_cents] (defaulting to 0) when building the estimated event. Co-Authored-By: Claude Opus 5 (1M context) --- openapi.yaml | 21 +++++++++++++++------ src/schemas/BillableMetricObject.yaml | 9 ++++++--- src/schemas/EventEstimateFeesInput.yaml | 6 ++++++ src/schemas/EventObject.yaml | 6 +++--- 4 files changed, 30 insertions(+), 12 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 55b2f9d3..6c725430 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -13533,9 +13533,11 @@ components: example: '2022-09-14T16:35:31Z' description: Creation date of the billable metric. expression: - type: string + type: + - string + - 'null' example: round((ended_at - started_at) * units) - description: Expression used to calculate the event units. The expression is evalutated for each event and the result is then used to calculate the total aggregated units. + description: Expression used to calculate the event units. The expression is evaluated for each event and the result is then used to calculate the total aggregated units. field_name: type: - string @@ -13544,7 +13546,7 @@ components: description: Property of the billable metric used for aggregating usage data. This field is not required for `count_agg`. aggregation_type: type: string - description: Aggregation method used to compute usage for this billable metric. + description: Aggregation method used to compute usage for this billable metric. `custom_agg` is only returned for metrics that use a custom aggregator; it cannot be set through this API. example: sum_agg enum: - count_agg @@ -13553,6 +13555,7 @@ components: - unique_count_agg - weighted_sum_agg - latest_agg + - custom_agg weighted_interval: type: - string @@ -19237,13 +19240,13 @@ components: type: string format: date-time example: '2022-04-29T08:59:51.123Z' - description: This field captures the Unix timestamp in seconds indicating the occurrence of the event in Coordinated Universal Time (UTC). If this timestamp is not provided, the API will automatically set it to the time of event reception. + description: The date and time at which the event occurred, in ISO 8601 format with millisecond precision and expressed in Coordinated Universal Time (UTC). When no timestamp is sent on the event, it is set to the time of event reception. precise_total_amount_cents: type: - string - 'null' example: '1234.56' - description: The precise total amount that was sent in the event payload. This filed is used by the `dynamic` pricing model. + description: The precise total amount that was sent in the event payload. This field is used by the `dynamic` pricing model. properties: type: object description: This field represents additional properties associated with the event, which are utilized in the calculation of the final fee. This object becomes mandatory when the targeted billable metric employs a `sum_agg`, `max_agg`, or `unique_count_agg` aggregation method. However, when using a simple `count_agg`, this object is not required. @@ -19273,7 +19276,7 @@ components: external_subscription_id: type: string example: sub_1234567890 - description: The unique identifier of the subscription within your application. It is a mandatory field when the customer possesses multiple subscriptions or when the `external_customer_id` is not provided. + description: The unique identifier of the subscription within your application, as sent on the event. It is the value Lago uses to attach the event to a subscription. created_at: type: - string @@ -19422,6 +19425,12 @@ components: type: string example: sub_1234567890 description: The unique identifier of the subscription within your application. + precise_total_amount_cents: + type: + - string + - 'null' + example: '1234.56' + description: The precise total amount in cents with precision used by the `dynamic` pricing model to compute the estimated usage amount. Defaults to `0` when omitted. properties: type: object description: This field represents additional properties associated with the event, which are utilized in the calculation of the final fee. This object becomes mandatory when the targeted billable metric employs a `sum_agg`, `max_agg`, or `unique_count_agg` aggregation method. However, when using a simple `count_agg`, this object is not required. Any property of the targeted billable metric can be sent here, in addition to the documented fields below. diff --git a/src/schemas/BillableMetricObject.yaml b/src/schemas/BillableMetricObject.yaml index cd6e73c5..4345a3fd 100644 --- a/src/schemas/BillableMetricObject.yaml +++ b/src/schemas/BillableMetricObject.yaml @@ -58,9 +58,11 @@ properties: example: "2022-09-14T16:35:31Z" description: "Creation date of the billable metric." expression: - type: string + type: + - string + - "null" example: "round((ended_at - started_at) * units)" - description: "Expression used to calculate the event units. The expression is evalutated for each event and the result is then used to calculate the total aggregated units." + description: "Expression used to calculate the event units. The expression is evaluated for each event and the result is then used to calculate the total aggregated units." field_name: type: - string @@ -69,7 +71,7 @@ properties: description: "Property of the billable metric used for aggregating usage data. This field is not required for `count_agg`." aggregation_type: type: string - description: "Aggregation method used to compute usage for this billable metric." + description: "Aggregation method used to compute usage for this billable metric. `custom_agg` is only returned for metrics that use a custom aggregator; it cannot be set through this API." example: "sum_agg" enum: - count_agg @@ -78,6 +80,7 @@ properties: - unique_count_agg - weighted_sum_agg - latest_agg + - custom_agg weighted_interval: type: - string diff --git a/src/schemas/EventEstimateFeesInput.yaml b/src/schemas/EventEstimateFeesInput.yaml index d02b454b..a66e4670 100644 --- a/src/schemas/EventEstimateFeesInput.yaml +++ b/src/schemas/EventEstimateFeesInput.yaml @@ -16,6 +16,12 @@ properties: type: string example: "sub_1234567890" description: The unique identifier of the subscription within your application. + precise_total_amount_cents: + type: + - string + - "null" + example: "1234.56" + description: The precise total amount in cents with precision used by the `dynamic` pricing model to compute the estimated usage amount. Defaults to `0` when omitted. properties: type: object description: This field represents additional properties associated with the event, which are utilized in the calculation of the final fee. This object becomes mandatory when the targeted billable metric employs a `sum_agg`, `max_agg`, or `unique_count_agg` aggregation method. However, when using a simple `count_agg`, this object is not required. Any property of the targeted billable metric can be sent here, in addition to the documented fields below. diff --git a/src/schemas/EventObject.yaml b/src/schemas/EventObject.yaml index 288515a2..188e3928 100644 --- a/src/schemas/EventObject.yaml +++ b/src/schemas/EventObject.yaml @@ -32,13 +32,13 @@ properties: type: string format: "date-time" example: "2022-04-29T08:59:51.123Z" - description: This field captures the Unix timestamp in seconds indicating the occurrence of the event in Coordinated Universal Time (UTC). If this timestamp is not provided, the API will automatically set it to the time of event reception. + description: The date and time at which the event occurred, in ISO 8601 format with millisecond precision and expressed in Coordinated Universal Time (UTC). When no timestamp is sent on the event, it is set to the time of event reception. precise_total_amount_cents: type: - string - "null" example: "1234.56" - description: The precise total amount that was sent in the event payload. This filed is used by the `dynamic` pricing model. + description: The precise total amount that was sent in the event payload. This field is used by the `dynamic` pricing model. properties: type: object description: This field represents additional properties associated with the event, which are utilized in the calculation of the final fee. This object becomes mandatory when the targeted billable metric employs a `sum_agg`, `max_agg`, or `unique_count_agg` aggregation method. However, when using a simple `count_agg`, this object is not required. @@ -68,7 +68,7 @@ properties: external_subscription_id: type: string example: "sub_1234567890" - description: The unique identifier of the subscription within your application. It is a mandatory field when the customer possesses multiple subscriptions or when the `external_customer_id` is not provided. + description: The unique identifier of the subscription within your application, as sent on the event. It is the value Lago uses to attach the event to a subscription. created_at: type: - string From c95830de6d77d604c676a39012cec5b92210c861 Mon Sep 17 00:00:00 2001 From: "Yohan R." <7434196+groyoh@users.noreply.github.com> Date: Wed, 7 Oct 2026 14:23:59 +0200 Subject: [PATCH 4/4] fix: drop deprecated custom_agg aggregation type ## Context `custom_agg` is a deprecated aggregation type. It cannot be created through the API and is only kept in lago-api for legacy metrics. ## Description The `custom_agg` enum value and the sentence describing it were removed from `BillableMetricObject.aggregation_type`, so the public contract does not present it as a supported value. --- openapi.yaml | 3 +-- src/schemas/BillableMetricObject.yaml | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 6c725430..5e89e67b 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -13546,7 +13546,7 @@ components: description: Property of the billable metric used for aggregating usage data. This field is not required for `count_agg`. aggregation_type: type: string - description: Aggregation method used to compute usage for this billable metric. `custom_agg` is only returned for metrics that use a custom aggregator; it cannot be set through this API. + description: Aggregation method used to compute usage for this billable metric. example: sum_agg enum: - count_agg @@ -13555,7 +13555,6 @@ components: - unique_count_agg - weighted_sum_agg - latest_agg - - custom_agg weighted_interval: type: - string diff --git a/src/schemas/BillableMetricObject.yaml b/src/schemas/BillableMetricObject.yaml index 4345a3fd..6dcbd3f0 100644 --- a/src/schemas/BillableMetricObject.yaml +++ b/src/schemas/BillableMetricObject.yaml @@ -71,7 +71,7 @@ properties: description: "Property of the billable metric used for aggregating usage data. This field is not required for `count_agg`." aggregation_type: type: string - description: "Aggregation method used to compute usage for this billable metric. `custom_agg` is only returned for metrics that use a custom aggregator; it cannot be set through this API." + description: "Aggregation method used to compute usage for this billable metric." example: "sum_agg" enum: - count_agg @@ -80,7 +80,6 @@ properties: - unique_count_agg - weighted_sum_agg - latest_agg - - custom_agg weighted_interval: type: - string