diff --git a/openapi.yaml b/openapi.yaml index ed460e2..e3c83bc 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': @@ -16347,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. @@ -16393,6 +16421,8 @@ components: example: region: - us-east-1 + 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. @@ -16433,6 +16463,8 @@ components: type: string filters: $ref: '#/components/schemas/CustomerChargeFiltersUsageObject' + presentation_breakdowns: + $ref: '#/components/schemas/CustomerChargePresentationBreakdownsObject' CustomerChargeUsageObject: type: object required: @@ -16532,6 +16564,8 @@ components: $ref: '#/components/schemas/CustomerChargeFiltersUsageObject' grouped_usage: $ref: '#/components/schemas/CustomerChargeGroupedUsageObject' + presentation_breakdowns: + $ref: '#/components/schemas/CustomerChargePresentationBreakdownsObject' CustomerUsageObject: type: object required: @@ -16593,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: @@ -16651,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: @@ -18269,6 +18515,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 +18652,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 +20054,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 94f1ed7..1866403 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 20ee1be..aa657c7 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 0000000..425af4c --- /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 3c624a5..ba39508 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/CustomerChargeFiltersUsageObject.yaml b/src/schemas/CustomerChargeFiltersUsageObject.yaml index 1ebecec..8d65e86 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/CustomerChargeGroupedUsageObject.yaml b/src/schemas/CustomerChargeGroupedUsageObject.yaml index 7feca80..276b834 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 0000000..f6eb0f4 --- /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 faa8049..2dff05a 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/CustomerProjectedChargeFiltersUsageObject.yaml b/src/schemas/CustomerProjectedChargeFiltersUsageObject.yaml new file mode 100644 index 0000000..a4fc35f --- /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 4baa116..99dee69 100644 --- a/src/schemas/CustomerProjectedChargeGroupedUsageObject.yaml +++ b/src/schemas/CustomerProjectedChargeGroupedUsageObject.yaml @@ -42,3 +42,7 @@ items: type: string filters: $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 eac754d..bdb2d3d 100644 --- a/src/schemas/CustomerProjectedChargeUsageObject.yaml +++ b/src/schemas/CustomerProjectedChargeUsageObject.yaml @@ -101,3 +101,7 @@ properties: $ref: "./CustomerProjectedChargeFiltersUsageObject.yaml" grouped_usage: $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 48e6fde..0012c59 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"