Lago Billable_metrics API

openapi: 3.2.0
info:
  title: Lago API documentation Billable Metrics API
  description: Lago API allows your application to push customer information and metrics (events) from your application to the billing application.
  version: 1.55.0
  license:
    name: AGPLv3
    url: https://github.com/getlago/lago-openapi/blob/main/LICENSE
  contact:
    email: tech@getlago.com
servers:
- url: https://api.getlago.com/api/v1
  description: US Lago cluster
- url: https://api.eu.getlago.com/api/v1
  description: EU Lago cluster
security:
- bearerAuth: []
tags:
- name: billable_metrics
  description: Everything about Billable metric collection
  externalDocs:
    description: Find out more
    url: https://getlago.com/docs/api-reference/billable-metrics/object
paths:
  /billable_metrics:
    post:
      tags:
      - billable_metrics
      summary: Create a billable metric
      description: This endpoint creates a new billable metric representing a pricing component of your application.
      operationId: createBillableMetric
      requestBody:
        description: Billable metric payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillableMetricCreateInput'
        required: true
      responses:
        '200':
          description: Billable metric created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillableMetric'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
      - billable_metrics
      summary: List all billable metrics
      description: This endpoint retrieves all existing billable metrics that represent pricing components of your application.
      operationId: findAllBillableMetrics
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: List of billable metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillableMetricsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /billable_metrics/evaluate_expression:
    post:
      tags:
      - billable_metrics
      summary: Evaluate an expression for a billable metric
      description: Evaluate an expression for a billable metric creation by providing the expression and test data
      operationId: evaluateBillableMetricExpression
      requestBody:
        description: Billable metric expression evaluation payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillableMetricEvaluateExpressionInput'
        required: true
      responses:
        '200':
          description: Billable metric expression evaluation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillableMetricEvaluateExpressionResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /billable_metrics/{code}:
    parameters:
    - name: code
      in: path
      description: Code of the existing billable metric.
      required: true
      schema:
        type: string
        example: storage
    put:
      tags:
      - billable_metrics
      summary: Update a billable metric
      description: 'This endpoint updates an existing billable metric representing a pricing component of your application.


        Once the billable metric is used by a plan charge, only `name`, `description` and `filters` are applied. The other fields are ignored.'
      operationId: updateBillableMetric
      requestBody:
        description: Billable metric payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillableMetricUpdateInput'
        required: true
      responses:
        '200':
          description: Billable metric updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillableMetric'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
      - billable_metrics
      summary: Delete a billable metric
      description: This endpoint deletes an existing billable metric representing a pricing component of your application.
      operationId: destroyBillableMetric
      responses:
        '200':
          description: Billable metric deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillableMetric'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    get:
      tags:
      - billable_metrics
      summary: Retrieve a billable metric
      description: This endpoint retrieves an existing billable metric that represents a pricing component of your application. The billable metric is identified by its unique code.
      operationId: findBillableMetric
      responses:
        '200':
          description: Billable metric
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillableMetric'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    PaginationMeta:
      type: object
      required:
      - current_page
      - total_pages
      - total_count
      properties:
        current_page:
          type: integer
          description: Current page.
          example: 2
        next_page:
          type:
          - integer
          - 'null'
          description: Next page.
          example: 3
        prev_page:
          type:
          - integer
          - 'null'
          description: Previous page.
          example: 1
        total_pages:
          type: integer
          description: Total number of pages.
          example: 4
        total_count:
          type: integer
          description: Total number of records.
          example: 70
    BillableMetricUpdateInput:
      type: object
      required:
      - billable_metric
      properties:
        billable_metric:
          $ref: '#/components/schemas/BillableMetricBaseInput'
    BillableMetricsPaginated:
      type: object
      required:
      - billable_metrics
      - meta
      properties:
        billable_metrics:
          type: array
          items:
            $ref: '#/components/schemas/BillableMetricObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    BillableMetricCreateInput:
      type: object
      required:
      - billable_metric
      properties:
        billable_metric:
          $ref: '#/components/schemas/BillableMetricBaseInput'
          required:
          - name
          - code
          - aggregation_type
    BillableMetricBaseInput:
      type: object
      properties:
        name:
          type: string
          example: Storage
          description: Name of the billable metric.
        code:
          type: string
          example: storage
          description: Unique code used to identify the billable metric associated with the API request. This code associates each event with the correct metric.
        description:
          type:
          - string
          - 'null'
          example: GB of storage used in my application
          description: Internal description of the billable metric.
        recurring:
          type: boolean
          example: false
          description: 'Defines if the billable metric is persisted billing period over billing period.


            - If set to `true`: the accumulated number of units calculated from the previous billing period is persisted to the next billing period.

            - If set to `false`: the accumulated number of units is reset to 0 at the end of the billing period.

            - If not defined in the request, default value is `false`.'
        expression:
          type:
          - string
          - 'null'
          example: round((event.properties.ended_at - event.properties.started_at) * event.properties.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.

            Event values are read with `event.code`, `event.timestamp` and `event.properties.<name>`.

            Accepted functions are `ceil`, `concat`, `floor`, `greatest`, `least` and `round` as well as `+`, `-`, `/` and `*` operations.

            `ceil`, `floor` and `round` accept an optional second parameter to specify the number of decimals.

            '
        rounding_function:
          type:
          - string
          - 'null'
          enum:
          - ceil
          - floor
          - round
          - null
          example: round
          description: Refers to the numeric value or mathematical expression that will be rounded based on the calculated number of billing units. Possible values are `round`, `ceil` and `floor`.
        rounding_precision:
          type:
          - integer
          - 'null'
          example: 2
          description: Specifies the number of decimal places to which the `rounding_function` will be rounded. It can be a positive or negative value.
        field_name:
          type:
          - string
          - 'null'
          example: gb
          description: Property of the billable metric used for aggregating usage data. This field is not required for `count_agg`.
        aggregation_type:
          type: string
          example: sum_agg
          description: Aggregation method used to compute usage for this billable metric.
          enum:
          - count_agg
          - sum_agg
          - max_agg
          - unique_count_agg
          - weighted_sum_agg
          - latest_agg
        weighted_interval:
          type:
          - string
          - 'null'
          enum:
          - seconds
          - null
          example: seconds
          description: Parameter exclusively utilized in conjunction with the `weighted_sum_agg` aggregation type. It serves to adjust the aggregation result by assigning weights and proration to the result based on time intervals. It is required when `aggregation_type` is `weighted_sum_agg`, and `seconds` is the only accepted value.
        filters:
          type: array
          description: 'List of filters of the billable metric. On update, this list replaces the existing filters: a filter that is not sent is deleted.'
          items:
            $ref: '#/components/schemas/BillableMetricFilterInput'
    BillableMetricFilterInput:
      type: object
      description: Values used to apply differentiated pricing based on additional event properties.
      required:
      - key
      - values
      properties:
        key:
          type: string
          example: region
          description: Filter key to add to the event properties payload
        values:
          type: array
          items:
            type: string
            example: us-east-1
          description: List of possible filter values
    BillableMetricEvaluateExpressionResult:
      type: object
      required:
      - expression_result
      properties:
        expression_result:
          type: object
          required:
          - value
          properties:
            value:
              type: string
              example: '2.0'
              description: Result of evaluating the expression. A numeric result is returned as a decimal string.
    ApiErrorUnprocessableEntity:
      type: object
      required:
      - status
      - error
      - code
      - error_details
      properties:
        status:
          type: integer
          format: int32
          example: 422
        error:
          type: string
          example: Unprocessable entity
        code:
          type: string
          example: validation_errors
        error_details:
          type: object
    BillableMetricObject:
      type: object
      required:
      - lago_id
      - name
      - code
      - aggregation_type
      - recurring
      - created_at
      - filters
      properties:
        lago_id:
          type: string
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: Unique identifier of the billable metric created by Lago.
        name:
          type: string
          example: Storage
          description: Name of the billable metric.
        code:
          type: string
          example: storage
          description: Unique code used to identify the billable metric associated with the API request. This code associates each event with the correct metric.
        description:
          type:
          - string
          - 'null'
          example: GB of storage used in my application
          description: Internal description of the billable metric.
        recurring:
          type: boolean
          example: false
          description: 'Defines if the billable metric is persisted billing period over billing period.


            - If set to `true`: the accumulated number of units calculated from the previous billing period is persisted to the next billing period.

            - If set to `false`: the accumulated number of units is reset to 0 at the end of the billing period.

            - If not defined in the request, default value is `false`.'
        rounding_function:
          type:
          - string
          - 'null'
          enum:
          - ceil
          - floor
          - round
          - null
          example: round
          description: Refers to the numeric value or mathematical expression that will be rounded based on the calculated number of billing units. Possible values are `round`, `ceil` and `floor`.
        rounding_precision:
          type:
          - integer
          - 'null'
          example: 2
          description: Specifies the number of decimal places to which the `rounding_function` will be rounded. It can be a positive or negative value.
        created_at:
          type: string
          format: date-time
          example: '2022-09-14T16:35:31Z'
          description: Creation date of the billable metric.
        expression:
          type:
          - string
          - 'null'
          example: round((event.properties.ended_at - event.properties.started_at) * event.properties.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
          - 'null'
          example: gb
          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.
          example: sum_agg
          enum:
          - count_agg
          - sum_agg
          - max_agg
          - unique_count_agg
          - weighted_sum_agg
          - latest_agg
        weighted_interval:
          type:
          - string
          - 'null'
          enum:
          - seconds
          - null
          example: seconds
          description: Parameter exclusively utilized in conjunction with the `weighted_sum_agg` aggregation type. It serves to adjust the aggregation result by assigning weights and proration to the result based on time intervals.
        filters:
          type: array
          items:
            $ref: '#/components/schemas/BillableMetricFilterObject'
    BillableMetricEvaluateExpressionInput:
      type: object
      required:
      - expression
      - event
      properties:
        expression:
          type: string
          example: round((event.properties.ended_at - event.properties.started_at) * event.properties.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.

            Event values are read with `event.code`, `event.timestamp` and `event.properties.<name>`.

            Accepted functions are `ceil`, `concat`, `floor`, `greatest`, `least` and `round` as well as `+`, `-`, `/` and `*` operations.

            `ceil`, `floor` and `round` accept an optional second parameter to specify the number of decimals.

            '
        event:
          type: object
          required:
          - code
          - properties
          properties:
            code:
              type: string
              example: storage
              description: The code that identifies a targeted billable metric.
            timestamp:
              anyOf:
              - type: integer
              - type: string
              example: '1651240791'
              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.

                '
            properties:
              type: object
              description: This field represents additional properties associated with the event. They can be used when evaluating the expression.
              additionalProperties:
                oneOf:
                - type: string
                - type: integer
                - type: number
              example:
                gb: 10
    ApiErrorUnauthorized:
      type: object
      required:
      - status
      - error
      properties:
        status:
          type: integer
          format: int32
          example: 401
        error:
          type: string
          example: Unauthorized
    BillableMetric:
      type: object
      required:
      - billable_metric
      properties:
        billable_metric:
          $ref: '#/components/schemas/BillableMetricObject'
    BillableMetricFilterObject:
      type: object
      description: Values used to apply differentiated pricing based on additional event properties.
      required:
      - key
      - values
      properties:
        key:
          type: string
          example: region
          description: Filter key to add to the event properties payload
        values:
          type: array
          items:
            type: string
            example: us-east-1
          description: List of possible filter values
    ApiErrorNotFound:
      type: object
      required:
      - status
      - error
      - code
      properties:
        status:
          type: integer
          format: int32
          example: 404
        error:
          type: string
          example: Not Found
        code:
          type: string
          example: object_not_found
    ApiErrorBadRequest:
      type: object
      required:
      - status
      - error
      properties:
        status:
          type: integer
          format: int32
          example: 400
        error:
          type: string
          example: Bad request
  responses:
    BadRequest:
      description: Bad Request error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorBadRequest'
    UnprocessableEntity:
      description: Unprocessable entity error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorUnprocessableEntity'
    NotFound:
      description: Not Found error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorNotFound'
    Unauthorized:
      description: Unauthorized error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorUnauthorized'
  parameters:
    page:
      name: page
      in: query
      description: Page number.
      required: false
      explode: true
      schema:
        type: integer
        example: 1
    per_page:
      name: per_page
      in: query
      description: Number of records per page.
      required: false
      explode: true
      schema:
        type: integer
        example: 20
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
externalDocs:
  description: Lago Github
  url: https://github.com/getlago
x-provenance:
  method: harvested
  publisher: Lago
  source: https://getlago.com/api/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)