From 994c5057fd3e5980d3e4756bd42b8cfb7248ae42 Mon Sep 17 00:00:00 2001 From: Tiago Lupepic Date: Wed, 29 Apr 2026 12:03:23 +0200 Subject: [PATCH 1/2] feat(presentation_group_keys): Update openapi yaml with presentation group keys feature - Update the responses of current usage and projected usage - Update the payload of creating charges - Update the properties with filter_by_presentation option in current usage --- openapi.yaml | 61 ++++++++++++++++++- src/resources/customer_current_usage.yaml | 15 +++++ src/schemas/ChargeObject.yaml | 2 +- src/schemas/ChargeObjectProperties.yaml | 24 ++++++++ src/schemas/ChargeOverridableInput.yaml | 2 +- .../CustomerChargeGroupedUsageObject.yaml | 2 + ...merChargePresentationBreakdownsObject.yaml | 14 +++++ src/schemas/CustomerChargeUsageObject.yaml | 2 + ...omerProjectedChargeGroupedUsageObject.yaml | 2 + .../CustomerProjectedChargeUsageObject.yaml | 2 + 10 files changed, 122 insertions(+), 4 deletions(-) create mode 100644 src/schemas/ChargeObjectProperties.yaml create mode 100644 src/schemas/CustomerChargePresentationBreakdownsObject.yaml diff --git a/openapi.yaml b/openapi.yaml index ed460e24..45cc950b 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2935,6 +2935,19 @@ paths: type: boolean default: false example: true + - name: filter_by_presentation[] + in: query + description: | + Filter `presentation_breakdowns` by a list of presentation group key values. Only breakdowns matching the provided values will be returned. Pass an empty array to disable `presentation_breakdowns` entirely. + required: false + explode: true + schema: + type: array + items: + type: string + example: + - engineering + - operations operationId: findCustomerCurrentUsage responses: '200': @@ -16393,6 +16406,21 @@ components: example: region: - us-east-1 + CustomerChargePresentationBreakdownsObject: + type: array + description: Array of usage breakdowns split by presentation group keys without affecting pricing or aggregation. + items: + type: object + properties: + presentation_by: + type: object + description: Key value list of event properties used for presentation grouping. + additionalProperties: + type: string + units: + type: string + example: '9.0' + description: The number of units consumed for a specific presentation group. CustomerChargeGroupedUsageObject: type: array description: Array of aggregated fees, grouped by the event properties defined in a `standard` charge model. @@ -16433,6 +16461,8 @@ components: type: string filters: $ref: '#/components/schemas/CustomerChargeFiltersUsageObject' + presentation_breakdowns: + $ref: '#/components/schemas/CustomerChargePresentationBreakdownsObject' CustomerChargeUsageObject: type: object required: @@ -16532,6 +16562,8 @@ components: $ref: '#/components/schemas/CustomerChargeFiltersUsageObject' grouped_usage: $ref: '#/components/schemas/CustomerChargeGroupedUsageObject' + presentation_breakdowns: + $ref: '#/components/schemas/CustomerChargePresentationBreakdownsObject' CustomerUsageObject: type: object required: @@ -18269,6 +18301,31 @@ components: pattern: ^[0-9]+.?[0-9]*$ description: The unit price, excluding tax, for a specific tier of a `volume` charge model. It is expressed as a decimal value. example: '0.5' + ChargeObjectProperties: + allOf: + - $ref: '#/components/schemas/ChargeProperties' + - type: object + properties: + presentation_group_keys: + type: array + description: Groups usage into sub-items on invoices for display only, without affecting pricing or aggregation. + items: + type: object + properties: + value: + type: string + description: The event property to group by. + example: region + options: + type: object + properties: + display_in_invoice: + type: boolean + example: true + example: + - value: region + options: + display_in_invoice: true ChargeFilterObject: type: object description: Values used to apply differentiated pricing based on additional event properties. @@ -18381,7 +18438,7 @@ components: description: 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. example: 1200 properties: - $ref: '#/components/schemas/ChargeProperties' + $ref: '#/components/schemas/ChargeObjectProperties' description: List of all thresholds utilized for calculating the charge. filters: type: array @@ -19783,7 +19840,7 @@ components: description: 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. example: 0 properties: - $ref: '#/components/schemas/ChargeProperties' + $ref: '#/components/schemas/ChargeObjectProperties' description: List of all thresholds utilized for calculating the charge. filters: type: array diff --git a/src/resources/customer_current_usage.yaml b/src/resources/customer_current_usage.yaml index 94f1ed78..1866403d 100644 --- a/src/resources/customer_current_usage.yaml +++ b/src/resources/customer_current_usage.yaml @@ -68,6 +68,21 @@ get: type: boolean default: false example: true + - name: filter_by_presentation[] + in: query + description: > + Filter `presentation_breakdowns` by a list of presentation group key values. + Only breakdowns matching the provided values will be returned. + Pass an empty array to disable `presentation_breakdowns` entirely. + required: false + explode: true + schema: + type: array + items: + type: string + example: + - engineering + - operations operationId: findCustomerCurrentUsage responses: '200': diff --git a/src/schemas/ChargeObject.yaml b/src/schemas/ChargeObject.yaml index 20ee1bef..aa657c74 100644 --- a/src/schemas/ChargeObject.yaml +++ b/src/schemas/ChargeObject.yaml @@ -82,7 +82,7 @@ properties: description: 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. example: 1200 properties: - $ref: "./ChargeProperties.yaml" + $ref: "./ChargeObjectProperties.yaml" description: List of all thresholds utilized for calculating the charge. filters: type: array diff --git a/src/schemas/ChargeObjectProperties.yaml b/src/schemas/ChargeObjectProperties.yaml new file mode 100644 index 00000000..425af4cc --- /dev/null +++ b/src/schemas/ChargeObjectProperties.yaml @@ -0,0 +1,24 @@ +allOf: + - $ref: "./ChargeProperties.yaml" + - type: object + properties: + presentation_group_keys: + type: array + description: Groups usage into sub-items on invoices for display only, without affecting pricing or aggregation. + items: + type: object + properties: + value: + type: string + description: The event property to group by. + example: region + options: + type: object + properties: + display_in_invoice: + type: boolean + example: true + example: + - value: region + options: + display_in_invoice: true diff --git a/src/schemas/ChargeOverridableInput.yaml b/src/schemas/ChargeOverridableInput.yaml index 3c624a55..ba39508d 100644 --- a/src/schemas/ChargeOverridableInput.yaml +++ b/src/schemas/ChargeOverridableInput.yaml @@ -10,7 +10,7 @@ properties: description: 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. example: 0 properties: - $ref: "./ChargeProperties.yaml" + $ref: "./ChargeObjectProperties.yaml" description: List of all thresholds utilized for calculating the charge. filters: type: array diff --git a/src/schemas/CustomerChargeGroupedUsageObject.yaml b/src/schemas/CustomerChargeGroupedUsageObject.yaml index 7feca809..276b8348 100644 --- a/src/schemas/CustomerChargeGroupedUsageObject.yaml +++ b/src/schemas/CustomerChargeGroupedUsageObject.yaml @@ -37,3 +37,5 @@ items: type: string filters: $ref: "./CustomerChargeFiltersUsageObject.yaml" + presentation_breakdowns: + $ref: "./CustomerChargePresentationBreakdownsObject.yaml" diff --git a/src/schemas/CustomerChargePresentationBreakdownsObject.yaml b/src/schemas/CustomerChargePresentationBreakdownsObject.yaml new file mode 100644 index 00000000..f6eb0f4f --- /dev/null +++ b/src/schemas/CustomerChargePresentationBreakdownsObject.yaml @@ -0,0 +1,14 @@ +type: array +description: Array of usage breakdowns split by presentation group keys without affecting pricing or aggregation. +items: + type: object + properties: + presentation_by: + type: object + description: Key value list of event properties used for presentation grouping. + additionalProperties: + type: string + units: + type: string + example: "9.0" + description: The number of units consumed for a specific presentation group. diff --git a/src/schemas/CustomerChargeUsageObject.yaml b/src/schemas/CustomerChargeUsageObject.yaml index faa8049e..2dff05ae 100644 --- a/src/schemas/CustomerChargeUsageObject.yaml +++ b/src/schemas/CustomerChargeUsageObject.yaml @@ -96,3 +96,5 @@ properties: $ref: "./CustomerChargeFiltersUsageObject.yaml" grouped_usage: $ref: "./CustomerChargeGroupedUsageObject.yaml" + presentation_breakdowns: + $ref: "./CustomerChargePresentationBreakdownsObject.yaml" diff --git a/src/schemas/CustomerProjectedChargeGroupedUsageObject.yaml b/src/schemas/CustomerProjectedChargeGroupedUsageObject.yaml index 4baa116d..74a9237d 100644 --- a/src/schemas/CustomerProjectedChargeGroupedUsageObject.yaml +++ b/src/schemas/CustomerProjectedChargeGroupedUsageObject.yaml @@ -42,3 +42,5 @@ items: type: string filters: $ref: "./CustomerChargeFiltersUsageObject.yaml" + presentation_breakdowns: + $ref: "./CustomerChargePresentationBreakdownsObject.yaml" diff --git a/src/schemas/CustomerProjectedChargeUsageObject.yaml b/src/schemas/CustomerProjectedChargeUsageObject.yaml index eac754d6..a88466fc 100644 --- a/src/schemas/CustomerProjectedChargeUsageObject.yaml +++ b/src/schemas/CustomerProjectedChargeUsageObject.yaml @@ -101,3 +101,5 @@ properties: $ref: "./CustomerProjectedChargeFiltersUsageObject.yaml" grouped_usage: $ref: "./CustomerProjectedChargeGroupedUsageObject.yaml" + presentation_breakdowns: + $ref: "./CustomerChargePresentationBreakdownsObject.yaml" From eab42d18e06627f23147495d7db23b64d080cac0 Mon Sep 17 00:00:00 2001 From: Tiago Lupepic Date: Fri, 15 May 2026 11:24:08 +0200 Subject: [PATCH 2/2] Update the usages to include filters presentation_breakdowns and projected_presentation_breakdowns --- openapi.yaml | 246 ++++++++++++++++-- .../CustomerChargeFiltersUsageObject.yaml | 2 + ...omerProjectedChargeFiltersUsageObject.yaml | 54 ++++ ...omerProjectedChargeGroupedUsageObject.yaml | 2 + .../CustomerProjectedChargeUsageObject.yaml | 2 + src/schemas/CustomerProjectedUsageObject.yaml | 2 +- 6 files changed, 291 insertions(+), 17 deletions(-) create mode 100644 src/schemas/CustomerProjectedChargeFiltersUsageObject.yaml diff --git a/openapi.yaml b/openapi.yaml index 45cc950b..e3c83bcd 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -16360,6 +16360,21 @@ components: type: string example: '0.5' description: The conversion rate from pricing units to the plan's currency. + CustomerChargePresentationBreakdownsObject: + type: array + description: Array of usage breakdowns split by presentation group keys without affecting pricing or aggregation. + items: + type: object + properties: + presentation_by: + type: object + description: Key value list of event properties used for presentation grouping. + additionalProperties: + type: string + units: + type: string + example: '9.0' + description: The number of units consumed for a specific presentation group. CustomerChargeFiltersUsageObject: type: array description: Array of filter object, representing multiple dimensions for a charge item. @@ -16406,21 +16421,8 @@ components: example: region: - us-east-1 - CustomerChargePresentationBreakdownsObject: - type: array - description: Array of usage breakdowns split by presentation group keys without affecting pricing or aggregation. - items: - type: object - properties: - presentation_by: - type: object - description: Key value list of event properties used for presentation grouping. - additionalProperties: - type: string - units: - type: string - example: '9.0' - description: The number of units consumed for a specific presentation group. + presentation_breakdowns: + $ref: '#/components/schemas/CustomerChargePresentationBreakdownsObject' CustomerChargeGroupedUsageObject: type: array description: Array of aggregated fees, grouped by the event properties defined in a `standard` charge model. @@ -16625,6 +16627,218 @@ components: properties: customer_usage: $ref: '#/components/schemas/CustomerUsageObject' + CustomerProjectedChargeFiltersUsageObject: + type: array + description: Array of filter object, representing multiple dimensions for a charge item. + required: + - values + - units + - projected_units + - events_count + - amount_cents + - projected_amount_cents + items: + type: object + properties: + units: + type: string + pattern: ^[0-9]+.?[0-9]*$ + example: '0.9' + description: The number of units consumed for a specific charge filter related to a charge item. + projected_units: + type: string + pattern: ^[0-9]+.?[0-9]*$ + example: '1.8' + description: The projected number of units that can be consumed for a specific charge filter related to a charge item. + amount_cents: + type: integer + example: 1000 + description: The amount in cents, tax excluded, consumed for a specific charge filter related to a charge item. + projected_amount_cents: + type: integer + example: 2000 + description: The projected amount in cents, tax excluded, that can be consumed for a specific charge filter related to a charge item. + events_count: + type: integer + example: 10 + description: The quantity of usage events that have been recorded for a particular charge filter during the specified time period. These events may also be referred to as the number of transactions in some contexts. + invoice_display_name: + type: string + description: Specifies the name that will be displayed on an invoice. + example: AWS eu-east-1 + pricing_unit_details: + $ref: '#/components/schemas/UsagePricingUnitDetailsObject' + values: + type: object + description: List of filter values applied to the usage. + additionalProperties: + type: array + items: + type: string + example: + region: + - us-east-1 + presentation_breakdowns: + $ref: '#/components/schemas/CustomerChargePresentationBreakdownsObject' + projected_presentation_breakdowns: + $ref: '#/components/schemas/CustomerChargePresentationBreakdownsObject' + CustomerProjectedChargeGroupedUsageObject: + type: array + description: Array of aggregated fees, grouped by the event properties defined in a `standard` charge model. + required: + - amount_cents + - projected_amount_cents + - events_count + - units + - projected_units + - grouped_by + - groups + items: + type: object + properties: + amount_cents: + type: integer + example: 1000 + description: The amount in cents, tax excluded, consumed for a specific group related to a charge item. + projected_amount_cents: + type: integer + example: 2000 + description: The projected amount in cents, tax excluded, that can be consumed for a specific group related to a charge item. + events_count: + type: integer + example: 10 + description: The quantity of usage events that have been recorded for a particular charge during the specified time period. These events may also be referred to as the number of transactions in some contexts. + units: + type: string + pattern: ^[0-9]+.?[0-9]*$ + example: '0.9' + description: The number of units consumed for a specific group related to a charge item. + projected_units: + type: string + pattern: ^[0-9]+.?[0-9]*$ + example: '1.8' + description: The projected number of units that can be consumed for a specific group related to a charge item. + pricing_unit_details: + $ref: '#/components/schemas/UsagePricingUnitDetailsObject' + grouped_by: + type: object + description: Key value list of event properties aggregated by the charge model + additionalProperties: + type: string + filters: + $ref: '#/components/schemas/CustomerChargeFiltersUsageObject' + presentation_breakdowns: + $ref: '#/components/schemas/CustomerChargePresentationBreakdownsObject' + projected_presentation_breakdowns: + $ref: '#/components/schemas/CustomerChargePresentationBreakdownsObject' + CustomerProjectedChargeUsageObject: + type: object + required: + - units + - projected_units + - events_count + - amount_cents + - projected_amount_cents + - amount_currency + - charge + - billable_metric + - groups + properties: + units: + type: string + pattern: ^[0-9]+.?[0-9]*$ + example: '1.0' + description: The number of units consumed by the customer for a specific charge item. + projected_units: + type: string + pattern: ^[0-9]+.?[0-9]*$ + example: '2.0' + description: The projected number of units that can be consumed by the customer for a specific charge item. + events_count: + type: integer + example: 10 + description: The quantity of usage events that have been recorded for a particular charge during the specified time period. These events may also be referred to as the number of transactions in some contexts. + amount_cents: + type: integer + example: 123 + description: The amount in cents, tax excluded, consumed by the customer for a specific charge item. + projected_amount_cents: + type: integer + example: 256 + description: The projected amount in cents, tax excluded, that can be consumed by the customer for a specific charge item. + amount_currency: + $ref: '#/components/schemas/Currency' + description: The currency of a usage item consumed by the customer. + example: EUR + pricing_unit_details: + $ref: '#/components/schemas/UsagePricingUnitDetailsObject' + charge: + type: object + description: Object listing all the properties for a specific charge item. + required: + - lago_id + - charge_model + properties: + lago_id: + type: string + format: uuid + example: 1a901a90-1a90-1a90-1a90-1a901a901a90 + description: Unique identifier assigned to the charge within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the charge's record within the Lago system. + charge_model: + type: string + description: The pricing model applied to this charge. Possible values are standard, `graduated`, `percentage`, `package` or `volume`. + enum: + - standard + - graduated + - package + - percentage + - volume + example: graduated + invoice_display_name: + type: string + description: 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. + example: Setup + billable_metric: + type: object + description: The related billable metric object. + required: + - lago_id + - name + - code + - aggregation_type + properties: + lago_id: + type: string + format: uuid + example: 1a901a90-1a90-1a90-1a90-1a901a901a90 + description: Unique identifier assigned to the billable metric within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the billable metric's record within the Lago system. + name: + type: string + example: Storage + description: The name of the billable metric used for this charge. + code: + type: string + example: storage + description: The code of the billable metric used for this charge. + aggregation_type: + type: string + description: The aggregation type of the billable metric used for this charge. Possible values are `count_agg`, `sum_agg`, `max_agg` or `unique_count_agg`. + enum: + - count_agg + - sum_agg + - max_agg + - unique_count_agg + - weighted_sum_agg + - latest_agg + example: sum_agg + filters: + $ref: '#/components/schemas/CustomerProjectedChargeFiltersUsageObject' + grouped_usage: + $ref: '#/components/schemas/CustomerProjectedChargeGroupedUsageObject' + presentation_breakdowns: + $ref: '#/components/schemas/CustomerChargePresentationBreakdownsObject' + projected_presentation_breakdowns: + $ref: '#/components/schemas/CustomerChargePresentationBreakdownsObject' CustomerProjectedUsageObject: type: object required: @@ -16683,7 +16897,7 @@ components: type: array description: Array of charges that comprise the current usage. It contains detailed information about individual charge items associated with the usage. items: - $ref: '#/components/schemas/CustomerChargeUsageObject' + $ref: '#/components/schemas/CustomerProjectedChargeUsageObject' CustomerProjectedUsage: type: object required: diff --git a/src/schemas/CustomerChargeFiltersUsageObject.yaml b/src/schemas/CustomerChargeFiltersUsageObject.yaml index 1ebececd..8d65e869 100644 --- a/src/schemas/CustomerChargeFiltersUsageObject.yaml +++ b/src/schemas/CustomerChargeFiltersUsageObject.yaml @@ -43,3 +43,5 @@ items: example: region: - us-east-1 + presentation_breakdowns: + $ref: "./CustomerChargePresentationBreakdownsObject.yaml" diff --git a/src/schemas/CustomerProjectedChargeFiltersUsageObject.yaml b/src/schemas/CustomerProjectedChargeFiltersUsageObject.yaml new file mode 100644 index 00000000..a4fc35f7 --- /dev/null +++ b/src/schemas/CustomerProjectedChargeFiltersUsageObject.yaml @@ -0,0 +1,54 @@ +type: array +description: Array of filter object, representing multiple dimensions for a charge item. +required: + - values + - units + - projected_units + - events_count + - amount_cents + - projected_amount_cents +items: + type: object + properties: + units: + type: string + pattern: "^[0-9]+.?[0-9]*$" + example: "0.9" + description: The number of units consumed for a specific charge filter related to a charge item. + projected_units: + type: string + pattern: "^[0-9]+.?[0-9]*$" + example: "1.8" + description: The projected number of units that can be consumed for a specific charge filter related to a charge item. + amount_cents: + type: integer + example: 1000 + description: The amount in cents, tax excluded, consumed for a specific charge filter related to a charge item. + projected_amount_cents: + type: integer + example: 2000 + description: The projected amount in cents, tax excluded, that can be consumed for a specific charge filter related to a charge item. + events_count: + type: integer + example: 10 + description: The quantity of usage events that have been recorded for a particular charge filter during the specified time period. These events may also be referred to as the number of transactions in some contexts. + invoice_display_name: + type: string + description: Specifies the name that will be displayed on an invoice. + example: "AWS eu-east-1" + pricing_unit_details: + $ref: "./UsagePricingUnitDetailsObject.yaml" + values: + type: object + description: "List of filter values applied to the usage." + additionalProperties: + type: array + items: + type: string + example: + region: + - us-east-1 + presentation_breakdowns: + $ref: "./CustomerChargePresentationBreakdownsObject.yaml" + projected_presentation_breakdowns: + $ref: "./CustomerChargePresentationBreakdownsObject.yaml" diff --git a/src/schemas/CustomerProjectedChargeGroupedUsageObject.yaml b/src/schemas/CustomerProjectedChargeGroupedUsageObject.yaml index 74a9237d..99dee697 100644 --- a/src/schemas/CustomerProjectedChargeGroupedUsageObject.yaml +++ b/src/schemas/CustomerProjectedChargeGroupedUsageObject.yaml @@ -44,3 +44,5 @@ items: $ref: "./CustomerChargeFiltersUsageObject.yaml" presentation_breakdowns: $ref: "./CustomerChargePresentationBreakdownsObject.yaml" + projected_presentation_breakdowns: + $ref: "./CustomerChargePresentationBreakdownsObject.yaml" diff --git a/src/schemas/CustomerProjectedChargeUsageObject.yaml b/src/schemas/CustomerProjectedChargeUsageObject.yaml index a88466fc..bdb2d3dc 100644 --- a/src/schemas/CustomerProjectedChargeUsageObject.yaml +++ b/src/schemas/CustomerProjectedChargeUsageObject.yaml @@ -103,3 +103,5 @@ properties: $ref: "./CustomerProjectedChargeGroupedUsageObject.yaml" presentation_breakdowns: $ref: "./CustomerChargePresentationBreakdownsObject.yaml" + projected_presentation_breakdowns: + $ref: "./CustomerChargePresentationBreakdownsObject.yaml" diff --git a/src/schemas/CustomerProjectedUsageObject.yaml b/src/schemas/CustomerProjectedUsageObject.yaml index 48e6fde6..0012c59f 100644 --- a/src/schemas/CustomerProjectedUsageObject.yaml +++ b/src/schemas/CustomerProjectedUsageObject.yaml @@ -55,4 +55,4 @@ properties: type: array description: Array of charges that comprise the current usage. It contains detailed information about individual charge items associated with the usage. items: - $ref: "./CustomerChargeUsageObject.yaml" + $ref: "./CustomerProjectedChargeUsageObject.yaml"