openapi: 3.1.0
info:
  title: Lago API documentation
  description: Lago API allows your application to push customer information and metrics (events) from your application to the billing application.
  version: 1.51.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: activity_logs
    description: Everything about Activity logs
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/audit-logs/activity-logs-object
  - name: analytics
    description: Everything about Analytics
  - name: api_logs
    description: Everything about API logs
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/audit-logs/api-logs-object
  - name: billable_metrics
    description: Everything about Billable metric collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/billable-metrics/object
  - name: features
    description: Everything about Feature collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/entitlements/features/feature-object
  - name: entitlements
    description: Everything about Entitlement collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/entitlements/plan-entitlements/plan-entitlement-object
  - name: billing_entities
    description: Everything about Billing Entities
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/billing-entities/object
  - name: customers
    description: Everything about Customer collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/customers/object
  - name: plans
    description: Everything about Plan collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/plans/object
  - name: subscriptions
    description: Everything about Subscription collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/subscriptions/subscription-object
  - name: events
    description: Everything about Event collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/events/event-object
  - name: organizations
    description: Everything about Organization collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/organizations/organization-object
  - name: taxes
    description: Everything about Tax collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/taxes/tax-object
  - name: coupons
    description: Everything about Coupon collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/coupons/coupon-object
  - name: add_ons
    description: Everything about Add-on collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/add-ons/add-on-object
  - name: fees
    description: Everything about Fees
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/invoices/invoice-object#fee-object
  - name: invoices
    description: Everything about Invoice collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/invoices/invoice-object
  - name: wallets
    description: Everything about Wallet collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/wallets/wallet-object
  - name: credit_notes
    description: Everything about Credit notes collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/credit-notes/credit-note-object
  - name: webhooks
    description: Everything about Webhooks
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/webhooks/format---signature#1-retrieve-the-public-key
  - name: webhook_endpoints
    description: Everything about Webhook Endpoints
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/webhook-endpoints/webhook-endpoint-object
  - name: payment_receipts
    description: Everything about Payment receipts
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/payment-receipts/payment-receipt-object
  - name: payment_requests
    description: Everything about PaymentRequests
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/payment-requests/payment-request-object
  - name: payments
    description: Everything about Payments
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/payments/payment-object
  - name: payment_methods
    description: Everything about Payment Methods
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/payment-methods/payment-method-object
externalDocs:
  description: Lago Github
  url: https://github.com/getlago
paths:
  /billing_entities:
    get:
      tags:
        - billing_entities
      summary: List all billing entities
      description: This endpoint returns a list of all billing entities in the organization
      operationId: listBillingEntities
      responses:
        '200':
          description: List of billing entities
          content:
            application/json:
              schema:
                type: object
                required:
                  - billing_entities
                properties:
                  billing_entities:
                    type: array
                    items:
                      $ref: '#/components/schemas/BillingEntityObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    post:
      tags:
        - billing_entities
      summary: Create a billing entity
      description: This endpoint is used to create a new billing entity
      operationId: createBillingEntity
      requestBody:
        description: The billing entity payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingEntityCreateInput'
        required: true
      responses:
        '200':
          description: Billing entity created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingEntityObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /billing_entities/{code}:
    parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The ID of the billing entity
    get:
      tags:
        - billing_entities
      summary: Retrieve a billing entity
      description: This endpoint returns a specific billing entity by its code
      operationId: getBillingEntity
      responses:
        '200':
          description: Billing entity details
          content:
            application/json:
              schema:
                type: object
                required:
                  - billing_entity
                properties:
                  billing_entity:
                    $ref: '#/components/schemas/BillingEntityObjectExtended'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    put:
      tags:
        - billing_entities
      summary: Update a billing entity
      description: This endpoint is used to update an existing billing entity
      operationId: updateBillingEntity
      requestBody:
        description: The billing entity update payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingEntityUpdateInput'
      responses:
        '200':
          description: Billing entity updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingEntityObjectExtended'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /activity_logs:
    get:
      tags:
        - activity_logs
      summary: List all activity logs
      description: This endpoint retrieves all existing activity logs that represent actions performed on application resources.
      operationId: findAllActivityLogs
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - name: from_date
          in: query
          description: Filter activity logs from a specific date.
          required: false
          explode: true
          schema:
            type: string
            format: date
            example: '2022-08-09'
        - name: to_date
          in: query
          description: Filter activity logs up to a specific date.
          required: false
          explode: true
          schema:
            type: string
            format: date
            example: '2022-08-09'
        - name: activity_types[]
          in: query
          description: Filter results by activity types
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
            example:
              - billing_metric.created
              - billing_metric.updated
        - name: activity_sources[]
          in: query
          description: Filter results by activity sources
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - api
                - front
                - system
            example:
              - api
              - front
        - name: user_emails[]
          in: query
          description: Filter results by user emails
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
            example:
              - dinesh@piedpiper.test
        - $ref: '#/components/parameters/external_customer_id'
        - $ref: '#/components/parameters/external_subscription_id'
        - name: resource_ids[]
          in: query
          description: Filter results by resources unique identifiers
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
              format: uuid
            example:
              - 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
              - 1a901a90-1a90-1a90-1a90-1a901a901a90
        - name: resource_types[]
          in: query
          description: Filter results by resource class types
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
            example:
              - BillableMetric
              - Invoice
      responses:
        '200':
          description: List of activity logs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityLogsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /activity_logs/{activity_id}:
    parameters:
      - name: activity_id
        in: path
        description: The Activity Id of the existing activity log.
        required: true
        schema:
          type: string
          example: bdc0eda6-ea52-4f72-a46a-94f47a89b546
    get:
      tags:
        - activity_logs
      summary: Retrieve an activity log
      description: This endpoint retrieves an existing activity log that represents an action performed on some resource. The activity log is identified by its unique activity_id.
      operationId: findActivityLog
      responses:
        '200':
          description: Activity Log
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityLog'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /add_ons:
    post:
      tags:
        - add_ons
      summary: Create an add-on
      description: This endpoint is used to create an add-on that can be then attached to a one-off invoice.
      operationId: createAddOn
      requestBody:
        description: Add-on payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddOnCreateInput'
        required: true
      responses:
        '200':
          description: Add-on created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddOn'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - add_ons
      summary: List all add-ons
      description: This endpoint is used to list all existing add-ons.
      operationId: findAllAddOns
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: Add-ons
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddOnsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /add_ons/{code}:
    parameters:
      - name: code
        in: path
        description: Unique code used to identify the add-on.
        required: true
        schema:
          type: string
          example: setup_fee
    put:
      tags:
        - add_ons
      summary: Update an add-on
      description: This endpoint is used to update an existing add-on.
      operationId: updateAddOn
      requestBody:
        description: Add-on payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddOnUpdateInput'
        required: true
      responses:
        '200':
          description: Add-on updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddOn'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - add_ons
      summary: Retrieve an add-on
      description: This endpoint is used to retrieve a specific add-on.
      operationId: findAddOn
      responses:
        '200':
          description: Add-on
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddOn'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - add_ons
      summary: Delete an add-on
      description: This endpoint is used to delete an existing add-on.
      operationId: destroyAddOn
      responses:
        '200':
          description: Add-on deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddOn'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api_logs:
    get:
      tags:
        - api_logs
      summary: List all api logs
      description: This endpoint retrieves all existing api logs that represent requests performed to Lago's API.
      operationId: findAllApiLogs
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - name: from_date
          in: query
          description: Filter api logs from a specific date.
          required: false
          explode: true
          schema:
            type: string
            format: date
            example: '2022-08-09'
        - name: to_date
          in: query
          description: Filter api logs up to a specific date.
          required: false
          explode: true
          schema:
            type: string
            format: date
            example: '2022-08-09'
        - name: http_methods[]
          in: query
          description: Filter results by HTTP methods
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - post
                - put
                - delete
            example:
              - post
              - put
        - name: http_statuses[]
          in: query
          description: Filter results by HTTP status or by generic request status
          required: false
          explode: true
          schema:
            type: array
            items:
              anyOf:
                - type: string
                  enum:
                    - succeeded
                    - failed
                - type: integer
                  minimum: 100
                  maximum: 599
            example:
              - failed
              - succeeded
              - 404
        - name: api_version
          in: query
          description: Filter results by API version
          required: false
          explode: true
          schema:
            type: string
            example: v1
        - name: request_paths
          in: query
          description: Filter results by the path of the request
          required: false
          explode: true
          schema:
            type: string
            example: /billable_metrics/
      responses:
        '200':
          description: List of api logs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiLogsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api_logs/{request_id}:
    parameters:
      - name: request_id
        in: path
        description: The Request Id of the existing api log.
        required: true
        schema:
          type: string
          example: bdc0eda6-ea52-4f72-a46a-94f47a89b546
    get:
      tags:
        - api_logs
      summary: Retrieve an api log
      description: This endpoint retrieves an existing api log that represents a request made to the API. The api log is identified by its unique request_id.
      operationId: findApiLog
      responses:
        '200':
          description: Api Log
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiLog'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /analytics/gross_revenue:
    get:
      tags:
        - analytics
      summary: List gross revenue
      description: Gross revenue is the sum of monthly `finalized` invoice payments and fees paid in advance that are not invoiceable. This total is calculated after deducting taxes and discounts.
      operationId: findAllGrossRevenues
      parameters:
        - name: currency
          in: query
          description: Currency of revenue analytics. Format must be ISO 4217.
          required: false
          explode: true
          schema:
            allOf:
              - $ref: '#/components/schemas/Currency'
              - example: USD
        - name: external_customer_id
          in: query
          description: The customer external unique identifier (provided by your own application). Use it to filter revenue analytics at the customer level.
          required: false
          explode: true
          schema:
            type: string
            example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        - $ref: '#/components/parameters/months'
      responses:
        '200':
          description: Gross revenue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrossRevenues'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /analytics/invoice_collection:
    get:
      tags:
        - analytics
      summary: List of finalized invoices
      description: Represents a monthly aggregation, detailing both the total count and the cumulative amount of invoices that have been marked as `finalized`. This report sorts invoices categorically based on their `payment_status`.
      operationId: findAllInvoiceCollections
      parameters:
        - name: currency
          in: query
          description: The currency of revenue analytics. Format must be ISO 4217.
          required: false
          explode: true
          schema:
            allOf:
              - $ref: '#/components/schemas/Currency'
              - example: USD
        - $ref: '#/components/parameters/months'
      responses:
        '200':
          description: Finalized invoice collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceCollections'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/invoiced_usage:
    get:
      tags:
        - analytics
      summary: List usage revenue
      description: Reports a monthly analysis focused on the revenue generated from all usage-based fees. It exclusively accounts for revenue that has been formally invoiced. Importantly, this report does not include revenue related to the usage in the current billing period, limiting its scope to previously invoiced amounts.
      operationId: findAllInvoicedUsages
      parameters:
        - name: currency
          in: query
          description: The currency of invoiced usage analytics. Format must be ISO 4217.
          required: false
          explode: true
          schema:
            allOf:
              - $ref: '#/components/schemas/Currency'
              - example: USD
        - $ref: '#/components/parameters/months'
      responses:
        '200':
          description: Invoiced usage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoicedUsages'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics/mrr:
    get:
      tags:
        - analytics
      summary: List MRR
      description: This endpoint is used to list MRR.
      operationId: findAllMrrs
      parameters:
        - name: currency
          in: query
          description: |-
            Quantifies the revenue generated from `subscription` fees on a monthly basis. This figure is calculated post-application of applicable taxes and deduction of any applicable discounts. The method of calculation varies based on the subscription billing cycle:

            - Revenue from `monthly` subscription invoices is included in the MRR for the month in which the invoice is issued.
            - Revenue from `quarterly` subscription invoices is distributed evenly over three months. This distribution applies to fees paid in advance (allocated to the next remaining months depending on calendar or anniversary billing) as well as to fees paid in arrears (allocated to the preceding months depending on calendar or anniversary billing).
            - Revenue from `yearly` subscription invoices is distributed evenly over twelve months. This allocation is applicable for fees paid in advance (spread over the next remaining months depending on calendar or anniversary billing) and for fees paid in arrears (spread over the previous months depending on calendar or anniversary billing).
            - Revenue from `semiannual` subscription invoices is distributed evenly over six months. This allocation is applicable for fees paid in advance (spread over the next remaining months depending on calendar or anniversary billing) and for fees paid in arrears (spread over the previous months depending on calendar or anniversary billing).
            - Revenue from `weekly` subscription invoices, the total revenue from all invoices issued within a month is summed up. This total is then divided by the number of invoices issued during that month, and the result is multiplied by 4.33, representing the average number of weeks in a month.
          required: false
          explode: true
          schema:
            allOf:
              - $ref: '#/components/schemas/Currency'
              - example: USD
        - $ref: '#/components/parameters/months'
      responses:
        '200':
          description: MRR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mrrs'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /analytics/overdue_balance:
    get:
      tags:
        - analytics
      summary: List overdue balance
      description: Overdue balance is the total amount associated with overdue invoices (invoices with pending or failed payments which are past their due dates).
      operationId: findAllOverdueBalances
      parameters:
        - name: currency
          in: query
          description: Currency of revenue analytics. Format must be ISO 4217.
          required: false
          explode: true
          schema:
            allOf:
              - $ref: '#/components/schemas/Currency'
              - example: USD
        - name: external_customer_id
          in: query
          description: The customer external unique identifier (provided by your own application). Use it to filter revenue analytics at the customer level.
          required: false
          explode: true
          schema:
            type: string
            example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        - $ref: '#/components/parameters/months'
      responses:
        '200':
          description: Overdue balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OverdueBalances'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /analytics/usage:
    get:
      tags:
        - analytics
      summary: List usage
      description: Returns usages.
      operationId: findAllUsages
      parameters:
        - name: time_granularity
          in: query
          description: The time granularity of usage analytics. Possible values are 'daily', 'weekly', 'monthly', 'yearly'.
          required: false
          schema:
            type: string
            enum:
              - daily
              - weekly
              - monthly
            example: monthly
        - name: currency
          in: query
          description: The currency of usage analytics. Format must be ISO 4217.
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/Currency'
              - example: USD
        - name: from_date
          in: query
          description: The start date of the period for which the usage analytics is calculated.
          required: false
          schema:
            type: string
            format: date
            example: '2023-11-01'
        - name: to_date
          in: query
          description: The end date of the period for which the usage analytics is calculated.
          required: false
          schema:
            type: string
            format: date
            example: '2023-11-30'
        - name: customer_type
          in: query
          description: The type of customer for which the usage analytics is calculated. Possible values are 'individual', 'company'.
          required: false
          schema:
            type: string
            enum:
              - individual
              - company
            example: individual
        - name: external_customer_id
          in: query
          description: The external identifier of the customer for which the usage analytics is calculated.
          required: false
          schema:
            type: string
            example: ext-customer-123
        - name: customer_country
          in: query
          description: The country of the customer for which the usage analytics is calculated.
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/Country'
              - example: US
        - name: external_subscription_id
          in: query
          description: The external identifier of the subscription for which the usage analytics is calculated.
          required: false
          schema:
            type: string
            example: ext-subscription-123
        - name: is_billable_metric_recurring
          in: query
          description: Indicates whether the billable metric associated with the usage is recurring.
          required: false
          schema:
            type: boolean
            example: true
        - name: plan_code
          in: query
          description: The code of the plan for which the usage analytics is calculated.
          required: false
          schema:
            type: string
            example: plan-code-123
        - name: billable_metric_code
          in: query
          description: The code of the usage-based billable metrics for which the usage analytics is calculated.
          required: false
          schema:
            type: string
            example: code1
      responses:
        '200':
          description: Usage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usages'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /applied_coupons:
    post:
      tags:
        - coupons
      summary: Apply a coupon to a customer
      description: This endpoint is used to apply a specific coupon to a customer, before or during a subscription.
      operationId: applyCoupon
      requestBody:
        description: Apply coupon payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppliedCouponInput'
        required: true
      responses:
        '200':
          description: Coupon applied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppliedCoupon'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - coupons
      summary: List all applied coupons
      description: This endpoint is used to list all applied coupons. You can filter by coupon status and by customer.
      operationId: findAllAppliedCoupons
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - name: status
          in: query
          description: The status of the coupon. Can be either `active` or `terminated`.
          required: false
          explode: true
          schema:
            type: string
            enum:
              - active
              - terminated
            example: active
        - name: external_customer_id
          in: query
          description: The customer external unique identifier (provided by your own application)
          required: false
          explode: true
          schema:
            type: string
            example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        - name: coupon_code[]
          in: query
          description: The code of the coupon applied to the customer. Use it to filter applied coupons by their code.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
            example:
              - BLACK_FRIDAY_2024
              - CHRISTMAS_2024
      responses:
        '200':
          description: Applied Coupons
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppliedCouponsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /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.
      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'
  /features:
    post:
      tags:
        - features
      summary: Create a feature
      description: This endpoint creates a new feature representing an entitlement component of your application.
      operationId: createFeature
      requestBody:
        description: Feature payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeatureCreateInput'
        required: true
      responses:
        '200':
          description: Feature created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feature'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - features
      summary: List all features
      description: This endpoint retrieves all existing features that represent entitlement components of your application.
      operationId: findAllFeatures
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - name: search_term
          in: query
          description: Search in name, code and description.
          required: false
          explode: true
          schema:
            type: string
      responses:
        '200':
          description: List of features
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeaturesPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /features/{code}:
    parameters:
      - name: code
        in: path
        description: Code of the existing feature.
        required: true
        schema:
          type: string
          example: seats
    put:
      tags:
        - features
      summary: Update a feature
      description: This endpoint updates an existing feature representing an entitlement component of your application.
      operationId: updateFeature
      requestBody:
        description: Feature payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeatureUpdateInput'
        required: true
      responses:
        '200':
          description: Feature updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feature'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
        - features
      summary: Delete a feature
      description: This endpoint deletes an existing feature representing an entitlement component of your application. Deleting a feature will remove it from all plans and subscriptions.
      operationId: destroyFeature
      responses:
        '200':
          description: Feature deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feature'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    get:
      tags:
        - features
      summary: Retrieve a feature
      description: This endpoint retrieves an existing feature that represents an entitlement component of your application. The feature is identified by its unique code.
      operationId: findFeature
      responses:
        '200':
          description: Feature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feature'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /features/{code}/privileges/{privilege_code}:
    parameters:
      - name: code
        in: path
        description: Code of the existing feature.
        required: true
        schema:
          type: string
          example: seats
      - name: privilege_code
        in: path
        description: Code of the existing privilege.
        required: true
        schema:
          type: string
          example: max_admins
    delete:
      tags:
        - features
      summary: Delete a privilege. Deleting a privilege removes it from all plans and subscriptions.
      description: Delete privilege from feature. Deleting a privilege removes it from all plans and subscriptions.
      operationId: deleteFeaturePrivilege
      responses:
        '200':
          description: Feature with deleted privilege.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feature'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /coupons:
    post:
      tags:
        - coupons
      summary: Create a coupon
      description: This endpoint is used to create a coupon that can be then attached to a customer to create a discount.
      operationId: createCoupon
      requestBody:
        description: Coupon payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CouponCreateInput'
        required: true
      responses:
        '200':
          description: Coupon created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Coupon'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - coupons
      summary: List all coupons
      description: This endpoint is used to list all existing coupons.
      operationId: findAllCoupons
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: Coupons
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CouponsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /coupons/{code}:
    parameters:
      - name: code
        in: path
        description: Unique code used to identify the coupon.
        required: true
        schema:
          type: string
          example: startup_deal
    put:
      tags:
        - coupons
      summary: Update a coupon
      description: This endpoint is used to update a coupon that can be then attached to a customer to create a discount.
      operationId: updateCoupon
      requestBody:
        description: Coupon payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CouponUpdateInput'
        required: true
      responses:
        '200':
          description: Coupon updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Coupon'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - coupons
      summary: Retrieve a coupon
      description: This endpoint is used to retrieve a specific coupon.
      operationId: findCoupon
      responses:
        '200':
          description: Coupon
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Coupon'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - coupons
      summary: Delete a coupon
      description: This endpoint is used to delete a coupon.
      operationId: destroyCoupon
      responses:
        '200':
          description: Coupon deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Coupon'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /credit_notes:
    post:
      tags:
        - credit_notes
      summary: Create a credit note
      description: This endpoint creates a new credit note.
      operationId: createCreditNote
      requestBody:
        description: Credit note payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditNoteCreateInput'
        required: true
      responses:
        '200':
          description: Credit note created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditNoteExtended'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - credit_notes
      summary: List all credit notes
      description: This endpoint list all existing credit notes.
      operationId: findAllCreditNotes
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - $ref: '#/components/parameters/external_customer_id'
        - name: issuing_date_from
          in: query
          description: Filter credit notes starting from a specific date.
          required: false
          explode: true
          schema:
            type: string
            format: date
            example: '2022-07-08'
        - name: issuing_date_to
          in: query
          description: Filter credit notes up to a specific date.
          required: false
          explode: true
          schema:
            type: string
            format: date
            example: '2022-08-09'
        - name: search_term
          in: query
          description: Search credit notes by id, number, customer name, customer external_id or customer email.
          required: false
          explode: true
          schema:
            type: string
            example: Jane
        - name: currency
          in: query
          description: Filter credit notes by currency. Possible values ISO 4217 currency codes.
          required: false
          explode: true
          schema:
            type: string
            example: EUR
        - name: reason
          in: query
          description: Filter credit notes by reasons. Possible values are `product_unsatisfactory`, `order_change`, `order_cancellation`, `fraudulent_charge`, `duplicated_charge` or `other`.
          required: false
          explode: true
          schema:
            type: string
            enum:
              - product_unsatisfactory
              - order_change
              - order_cancellation
              - fraudulent_charge
              - duplicated_charge
              - other
        - name: credit_status
          in: query
          description: Filter credit notes by credit status. Possible values are `available`, `consumed`  or `voided`.
          required: false
          explode: true
          schema:
            type: string
            enum:
              - available
              - consumed
              - voided
        - name: refund_status
          in: query
          description: Filter credit notes by refund status. Possible values are `pending`, `succeeded`  or `failed`.
          required: false
          explode: true
          schema:
            type: string
            enum:
              - pending
              - succeeded
              - failed
        - name: invoice_number
          in: query
          description: Filter credit notes by their related invoice number.
          required: false
          explode: true
          schema:
            type: string
            example: INV-001-002
        - name: amount_from
          in: query
          description: Filter credit notes of at least a specific amount. This parameter must be defined in cents to ensure consistent handling for all currency types.
          required: false
          explode: true
          schema:
            type: integer
            example: 9000
        - name: amount_to
          in: query
          description: Filter credit notes up to a specific amount. This parameter must be defined in cents to ensure consistent handling for all currency types.
          required: false
          explode: true
          schema:
            type: integer
            example: 100000
        - name: self_billed
          in: query
          description: Filter credit notes belonging to a self billed invoice. Possible values are `true` or `false`.
          required: false
          explode: true
          schema:
            type: boolean
            example: true
        - name: billing_entity_codes[]
          in: query
          description: Filter credit notes by billing entity codes.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
            example:
              - billing_entity_code_1
              - billing_entity_code_2
      responses:
        '200':
          description: Credit notes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditNotesPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /credit_notes/{lago_id}:
    parameters:
      - name: lago_id
        in: path
        description: The credit note unique identifier, created by Lago.
        required: true
        schema:
          type: string
          example: '12345'
    put:
      tags:
        - credit_notes
      summary: Update a credit note
      description: This endpoint updates an existing credit note.
      operationId: updateCreditNote
      requestBody:
        description: Credit note update payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditNoteUpdateInput'
        required: true
      responses:
        '200':
          description: Credit note updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditNoteExtended'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - credit_notes
      summary: Retrieve a credit note
      description: This endpoint retrieves an existing credit note.
      operationId: findCreditNote
      responses:
        '200':
          description: Credit note
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditNoteExtended'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /credit_notes/{lago_id}/download:
    post:
      tags:
        - credit_notes
      summary: Download a credit note PDF
      description: This endpoint downloads the PDF of an existing credit note.
      parameters:
        - name: lago_id
          in: path
          description: The credit note unique identifier, created by Lago.
          required: true
          schema:
            type: string
            format: uuid
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
      operationId: downloadCreditNote
      responses:
        '200':
          description: Credit note PDF
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditNote'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /credit_notes/estimate:
    post:
      tags:
        - credit_notes
      summary: Estimate amounts for a new credit note
      description: This endpoint allows you to retrieve amounts for a new credit note creation.
      requestBody:
        description: Credit note estimate payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditNoteEstimateInput'
      operationId: estimateCreditNote
      responses:
        '200':
          description: Credit note amounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditNoteEstimated'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /credit_notes/{lago_id}/void:
    put:
      tags:
        - credit_notes
      summary: Void available credit
      description: This endpoint voids the available credit linked to a specific credit note.
      parameters:
        - name: lago_id
          in: path
          description: The credit note unique identifier, created by Lago.
          required: true
          schema:
            type: string
            format: uuid
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
      operationId: voidCreditNote
      responses:
        '200':
          description: Credit note voided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditNoteExtended'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/NotAllowed'
  /credit_notes/{lago_id}/metadata:
    post:
      tags:
        - credit_notes
      summary: Replace credit note metadata
      description: |-
        This endpoint replaces all existing metadata on a credit note with the provided key-value pairs.
        Any existing metadata keys not included in the request will be removed.
      parameters:
        - name: lago_id
          in: path
          description: The credit note unique identifier, created by Lago.
          required: true
          schema:
            type: string
            format: uuid
            example: 1f615414-ceb0-11f0-94bf-0f2d5b311aba
      operationId: replaceCreditNoteMetadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditNoteMetadataResponse'
      responses:
        '200':
          description: Credit note metadata replaced
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditNoteMetadataResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    patch:
      tags:
        - credit_notes
      summary: Merge credit note metadata
      description: |-
        This endpoint merges the provided metadata with existing metadata on the credit note.
        Existing keys not in the request are preserved. New keys are added, existing keys are updated.
      parameters:
        - name: lago_id
          in: path
          description: The credit note unique identifier, created by Lago.
          required: true
          schema:
            type: string
            format: uuid
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
      operationId: mergeCreditNoteMetadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditNoteMetadataResponse'
      responses:
        '200':
          description: Credit note metadata merged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditNoteMetadataResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
        - credit_notes
      summary: Delete all credit note metadata
      description: This endpoint removes all metadata from a credit note.
      parameters:
        - name: lago_id
          in: path
          description: The credit note unique identifier, created by Lago.
          required: true
          schema:
            type: string
            format: uuid
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
      operationId: deleteAllCreditNoteMetadata
      responses:
        '200':
          description: Credit note metadata deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditNoteMetadataResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /credit_notes/{lago_id}/metadata/{key}:
    delete:
      tags:
        - credit_notes
      summary: Delete a metadata key
      description: This endpoint removes a single metadata key from a credit note.
      parameters:
        - name: lago_id
          in: path
          description: The credit note unique identifier, created by Lago.
          required: true
          schema:
            type: string
            format: uuid
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        - name: key
          in: path
          description: The metadata key to delete.
          required: true
          schema:
            type: string
            example: external_id
      operationId: deleteCreditNoteMetadataKey
      responses:
        '200':
          description: Metadata key deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditNoteMetadataResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers:
    post:
      tags:
        - customers
      summary: Create a customer
      description: This endpoint creates a new customer.
      operationId: createCustomer
      requestBody:
        description: Customer payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerCreateInput'
        required: true
      responses:
        '200':
          description: Customer created or updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - customers
      summary: List all customers
      description: This endpoint retrieves all existing customers.
      operationId: findAllCustomers
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - name: account_type[]
          in: query
          description: Filter customers by account type.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - customer
                - partner
            example:
              - customer
              - partner
        - name: billing_entity_codes[]
          in: query
          description: Filter customers by billing entity codes.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
            example:
              - billing_entity_code_1
              - billing_entity_code_2
        - name: search_term
          in: query
          description: Filter customers by search term. This will filter all customers whose name, firstname, lastname, legal name, external id or email contain the search term.
          required: false
          schema:
            type: string
            example: John Doe
        - name: countries[]
          in: query
          description: Filter customers by countries. Possible values are the ISO 3166-1 alpha-2 codes.
          required: false
          explode: true
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Country'
            example:
              - US
              - FR
        - name: states[]
          in: query
          description: Filter customers by states.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
            example:
              - CA
              - Paris
        - name: zipcodes[]
          in: query
          description: Filter customers by zipcodes.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
            example:
              - '10115'
              - '75001'
        - name: currencies[]
          in: query
          description: Filter customers by currencies.
          required: false
          explode: true
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Currency'
            example:
              - USD
              - EUR
        - name: has_tax_identification_number
          in: query
          description: Filter customers by whether they have a tax identification number or not.
          required: false
          schema:
            type: boolean
            example: true
        - name: metadata[key]
          in: query
          description: Filter customers by metadata. Replace `key` with the actual metadata key you want to match, and provide the corresponding value. Providing empty value will search for customers without given metadata key. For example, `metadata[is_synced]=true&metadata[last_synced_at]=`.
          required: false
          explode: true
          schema:
            type: string
            example: value
        - name: customer_type
          in: query
          description: Filter customers by customer type.
          required: false
          schema:
            type: string
            enum:
              - company
              - individual
            example: company
        - name: has_customer_type
          in: query
          description: Filter customers by whether they have a customer type or not.
          required: false
          schema:
            type: boolean
            example: true
      responses:
        '200':
          description: List of customers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomersPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers/{external_customer_id}:
    parameters:
      - name: external_customer_id
        in: path
        description: The customer external unique identifier (provided by your own application)
        required: true
        schema:
          type: string
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
    get:
      tags:
        - customers
      summary: Retrieve a customer
      description: This endpoint retrieves an existing customer.
      operationId: findCustomer
      responses:
        '200':
          description: Customer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - customers
      summary: Delete a customer
      description: This endpoint deletes an existing customer.
      operationId: destroyCustomer
      responses:
        '200':
          description: Customer deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{external_customer_id}/applied_coupons:
    get:
      tags:
        - customers
        - coupons
      summary: List all customer's applied coupons
      description: This endpoint is used to list all applied coupons for a customer.
      operationId: findAllCustomerAppliedCoupons
      parameters:
        - $ref: '#/components/parameters/external_customer_id_path'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - name: status
          in: query
          description: The status of the coupon. Can be either `active` or `terminated`.
          required: false
          explode: true
          schema:
            type: string
            enum:
              - active
              - terminated
            example: active
        - name: coupon_code[]
          in: query
          description: The code of the coupon applied to the customer. Use it to filter applied coupons by their code.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
            example:
              - BLACK_FRIDAY_2024
              - CHRISTMAS_2024
      responses:
        '200':
          description: Applied Coupons
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppliedCouponsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{external_customer_id}/applied_coupons/{applied_coupon_id}:
    delete:
      tags:
        - coupons
        - customers
      summary: Delete an applied coupon
      description: This endpoint is used to delete a specific coupon that has been applied to a customer.
      parameters:
        - $ref: '#/components/parameters/external_customer_id_path'
        - name: applied_coupon_id
          in: path
          description: Unique identifier of the applied coupon, created by Lago.
          required: true
          explode: true
          schema:
            type: string
            format: uuid
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
      operationId: deleteAppliedCoupon
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppliedCoupon'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{external_customer_id}/credit_notes:
    get:
      tags:
        - customers
        - credit_notes
      summary: List all customer's credit notes
      description: This endpoint list all existing credit notes for a customer.
      operationId: findAllCustomerCreditNotes
      parameters:
        - $ref: '#/components/parameters/external_customer_id_path'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - name: issuing_date_from
          in: query
          description: Filter credit notes starting from a specific date.
          required: false
          explode: true
          schema:
            type: string
            format: date
            example: '2022-07-08'
        - name: issuing_date_to
          in: query
          description: Filter credit notes up to a specific date.
          required: false
          explode: true
          schema:
            type: string
            format: date
            example: '2022-08-09'
        - name: search_term
          in: query
          description: Search credit notes by id, number, customer name, customer external_id or customer email.
          required: false
          explode: true
          schema:
            type: string
            example: Jane
        - name: reason
          in: query
          description: Filter credit notes by reasons. Possible values are `product_unsatisfactory`, `order_change`, `order_cancellation`, `fraudulent_charge`, `duplicated_charge` or `other`.
          required: false
          explode: true
          schema:
            type: string
            enum:
              - product_unsatisfactory
              - order_change
              - order_cancellation
              - fraudulent_charge
              - duplicated_charge
              - other
        - name: credit_status
          in: query
          description: Filter credit notes by credit status. Possible values are `available`, `consumed`  or `voided`.
          required: false
          explode: true
          schema:
            type: string
            enum:
              - available
              - consumed
              - voided
        - name: refund_status
          in: query
          description: Filter credit notes by refund status. Possible values are `pending`, `succeeded`  or `failed`.
          required: false
          explode: true
          schema:
            type: string
            enum:
              - pending
              - succeeded
              - failed
        - name: invoice_number
          in: query
          description: Filter credit notes by their related invoice number.
          required: false
          explode: true
          schema:
            type: string
            example: INV-001-002
        - name: amount_from
          in: query
          description: Filter credit notes of at least a specific amount. This parameter must be defined in cents to ensure consistent handling for all currency types.
          required: false
          explode: true
          schema:
            type: integer
            example: 9000
        - name: amount_to
          in: query
          description: Filter credit notes up to a specific amount. This parameter must be defined in cents to ensure consistent handling for all currency types.
          required: false
          explode: true
          schema:
            type: integer
            example: 100000
        - name: self_billed
          in: query
          description: Filter credit notes belonging to a self billed invoice. Possible values are `true` or `false`.
          required: false
          explode: true
          schema:
            type: boolean
            example: true
      responses:
        '200':
          description: Credit notes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditNotesPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{external_customer_id}/invoices:
    get:
      tags:
        - customers
        - invoices
      summary: List all customer's invoices
      description: This endpoint is used for retrieving all invoices of a customer.
      operationId: findAllCustomerInvoices
      parameters:
        - $ref: '#/components/parameters/external_customer_id_path'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - name: amount_from
          in: query
          description: Filter invoices of at least a specific amount. This parameter must be defined in cents to ensure consistent handling for all currency types.
          required: false
          explode: true
          schema:
            type: integer
            example: 9000
        - name: amount_to
          in: query
          description: Filter invoices up to a specific amount. This parameter must be defined in cents to ensure consistent handling for all currency types.
          required: false
          explode: true
          schema:
            type: integer
            example: 100000
        - name: issuing_date_from
          in: query
          description: Filter invoices starting from a specific date.
          required: false
          explode: true
          schema:
            type: string
            format: date
            example: '2022-07-08'
        - name: issuing_date_to
          in: query
          description: Filter invoices up to a specific date.
          required: false
          explode: true
          schema:
            type: string
            format: date
            example: '2022-08-09'
        - name: status
          in: query
          description: Filter invoices by status. Possible values are `draft` or `finalized`.
          required: false
          explode: true
          schema:
            type: string
            enum:
              - draft
              - finalized
        - name: payment_status
          in: query
          description: Filter invoices by payment status. Possible values are `pending`, `failed` or `succeeded`.
          required: false
          explode: true
          schema:
            type: string
            enum:
              - pending
              - failed
              - succeeded
        - name: payment_overdue
          in: query
          description: Filter invoices by payment_overdue. Possible values are `true` or `false`.
          required: false
          explode: true
          schema:
            type: boolean
            example: true
        - name: search_term
          in: query
          description: Search invoices by id, number, customer name, customer external_id or customer email.
          required: false
          explode: true
          schema:
            type: string
            example: Jane
        - name: payment_dispute_lost
          in: query
          description: Filter invoices with a payment dispute lost. Possible values are `true` or `false`.
          required: false
          explode: true
          schema:
            type: boolean
            example: true
        - name: invoice_type
          in: query
          description: Filter invoices by invoice type. Possible values are `subscription`, `add_on`, `credit`, `one_off`, `advance_charges` or `progressive_billing`.
          required: false
          explode: true
          schema:
            type: string
            enum:
              - subscription
              - add_on
              - credit
              - one_off
              - advance_charges
              - progressive_billing
        - name: self_billed
          in: query
          description: Filter invoices by self billed. Possible values are `true` or `false`.
          required: false
          explode: true
          schema:
            type: boolean
            example: true
        - name: metadata[key]
          in: query
          description: Filter invoices by metadata. Replace `key` with the actual metadata key you want to match, and provide the corresponding value. Providing empty value will search for invoice without given metadata key. For example, `metadata[color]=blue`.
          required: false
          explode: true
          schema:
            type: string
            example: someValue
      responses:
        '200':
          description: Invoices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoicesPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /customers/{external_customer_id}/payments:
    get:
      tags:
        - customers
        - payments
      summary: List all customer's payments
      description: This endpoint is used to list all payments of a customer
      operationId: findAllCustomerPayments
      parameters:
        - $ref: '#/components/parameters/external_customer_id_path'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - name: invoice_id
          in: query
          description: Unique identifier assigned to the invoice within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the invoice's record within the Lago system.
          required: false
          schema:
            type: string
            format: uuid
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
      responses:
        '200':
          description: Payments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{external_customer_id}/payment_requests:
    get:
      tags:
        - customers
        - payment_requests
      summary: List all customer's payment requests
      description: This endpoint is used to list all existing payment requests of a customer.
      operationId: findAllCustomerPaymentRequests
      parameters:
        - $ref: '#/components/parameters/external_customer_id_path'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - $ref: '#/components/parameters/payment_status'
        - name: billing_entity_codes[]
          in: query
          description: Filter payment requests by billing entity codes.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
            example:
              - billing_entity_code_1
              - billing_entity_code_2
      responses:
        '200':
          description: PaymentRequests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequestsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{external_customer_id}/portal_url:
    get:
      tags:
        - customers
      summary: Get a customer portal URL
      description: |-
        Retrieves an embeddable link for displaying a customer portal.

        This endpoint allows you to fetch the URL that can be embedded to provide customers access to a dedicated portal
      parameters:
        - name: external_customer_id
          in: path
          description: External ID of the existing customer
          required: true
          schema:
            type: string
            example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
      operationId: getCustomerPortalUrl
      responses:
        '200':
          description: Portal URL
          content:
            application/json:
              schema:
                type: object
                required:
                  - customer
                properties:
                  customer:
                    type: object
                    required:
                      - portal_url
                    properties:
                      portal_url:
                        type: string
                        example: https://app.lago.com/customer-portal/1234567890
                        description: An embeddable link for displaying a customer portal
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{external_customer_id}/subscriptions:
    get:
      tags:
        - customers
        - subscriptions
      summary: List all customer's subscriptions
      description: This endpoint retrieves all active subscriptions for a customer.
      operationId: findAllCustomerSubscriptions
      parameters:
        - $ref: '#/components/parameters/external_customer_id_path'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - name: plan_code
          in: query
          description: The unique code representing the plan to be attached to the customer. This code must correspond to the code property of one of the active plans.
          required: false
          explode: true
          schema:
            type: string
            example: premium
        - name: status[]
          in: query
          description: 'If the field is not defined, Lago will return only `active` subscriptions. However, if you wish to fetch subscriptions by different status you can define them in a status[] query param. Available filter values: `pending`, `canceled`, `terminated`, `active`.'
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - pending
                - canceled
                - terminated
                - active
            example:
              - active
              - pending
        - name: billing_entity_codes[]
          in: query
          description: Filter subscriptions by billing entity codes.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
            example:
              - billing_entity_code_1
              - billing_entity_code_2
      responses:
        '200':
          description: List of subscriptions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{external_customer_id}/wallets:
    parameters:
      - $ref: '#/components/parameters/external_customer_id_path'
    post:
      tags:
        - wallets
      summary: Create a wallet
      description: This endpoint is used to create a wallet with prepaid credits.
      operationId: createCustomerWallet
      requestBody:
        description: Wallet payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletCreateInput'
        required: true
      responses:
        '200':
          description: Wallet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Wallet'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - wallets
      summary: List all customer's wallets
      description: This endpoint is used to list all wallets with prepaid credits of a customer
      operationId: findAllCustomerWallets
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - name: billing_entity_codes[]
          in: query
          description: Filter wallets by billing entity codes.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
            example:
              - billing_entity_code_1
              - billing_entity_code_2
      responses:
        '200':
          description: Wallets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{external_customer_id}/wallets/{code}:
    parameters:
      - $ref: '#/components/parameters/external_customer_id_path'
      - name: code
        in: path
        description: A unique wallet identifier within a customer. It is either set by the user at creation or auto-generated by Lago if not provided.
        required: true
        schema:
          type: string
          example: wallet-code
    put:
      tags:
        - wallets
      summary: Update a wallet
      description: This endpoint is used to update an existing wallet with prepaid credits.
      operationId: updateCustomerWallet
      requestBody:
        description: Wallet update payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletUpdateInput'
        required: true
      responses:
        '200':
          description: Wallet updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Wallet'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - wallets
      summary: Retrieve a wallet
      description: This endpoint is used to retrieve an existing wallet with prepaid credits.
      operationId: findCustomerWallet
      responses:
        '200':
          description: Wallet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Wallet'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - wallets
      summary: Terminate a wallet
      description: This endpoint is used to terminate an existing wallet with prepaid credits.
      operationId: destroyCustomerWallet
      responses:
        '200':
          description: Wallet terminated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Wallet'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /customers/{external_customer_id}/wallets/{wallet_code}/metadata:
    parameters:
      - $ref: '#/components/parameters/external_customer_id_path'
      - $ref: '#/components/parameters/wallet_code'
    post:
      tags:
        - wallets
      summary: Replace wallet metadata
      description: |-
        This endpoint replaces all existing metadata on a wallet with the provided key-value pairs.
        Any existing metadata keys not included in the request will be removed.
      operationId: replaceCustomerWalletMetadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletMetadataResponse'
      responses:
        '200':
          description: Wallet metadata replaced
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletMetadataResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    patch:
      tags:
        - wallets
      summary: Merge wallet metadata
      description: |-
        This endpoint merges the provided metadata with existing metadata on the wallet.
        Existing keys not in the request are preserved. New keys are added, existing keys are updated.
      operationId: mergeCustomerWalletMetadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletMetadataResponse'
      responses:
        '200':
          description: Wallet metadata merged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletMetadataResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
        - wallets
      summary: Delete all wallet metadata
      description: This endpoint removes all metadata from a wallet.
      operationId: deleteAllCustomerWalletMetadata
      responses:
        '200':
          description: Wallet metadata deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletMetadataResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{external_customer_id}/wallets/{wallet_code}/metadata/{key}:
    parameters:
      - $ref: '#/components/parameters/external_customer_id_path'
      - $ref: '#/components/parameters/wallet_code'
    delete:
      tags:
        - wallets
      summary: Delete a metadata key
      description: This endpoint removes a single metadata key from a wallet.
      parameters:
        - name: key
          in: path
          description: The metadata key to delete.
          required: true
          schema:
            type: string
            example: external_id
      operationId: deleteCustomerWalletMetadataKey
      responses:
        '200':
          description: Metadata key deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletMetadataResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{external_customer_id}/wallets/{wallet_code}/alerts:
    parameters:
      - $ref: '#/components/parameters/external_customer_id_path'
      - $ref: '#/components/parameters/wallet_code'
    get:
      tags:
        - wallets
      summary: List wallet alerts
      description: This endpoint enables the retrieval of all alerts for a wallet.
      operationId: getCustomerWalletAlerts
      responses:
        '200':
          description: Wallet alerts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletAlerts'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
        - wallets
      summary: Create wallet alert(s)
      description: This endpoint allows you to create new alerts for a wallet. Send a single alert object wrapped in `alert` key to create one alert, or an array of alert objects wrapped in `alerts` key to create multiple alerts atomically.
      operationId: createCustomerWalletAlert
      requestBody:
        description: Create a new alert for a wallet
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/WalletAlertCreateInput'
                - $ref: '#/components/schemas/WalletAlertBatchCreateInput'
        required: true
      responses:
        '200':
          description: Wallet alert(s) created
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/WalletAlert'
                  - $ref: '#/components/schemas/WalletAlerts'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
        - wallets
      summary: Delete all wallet alerts
      description: This endpoint allows you to delete all alerts for a wallet.
      operationId: deleteAllCustomerWalletAlerts
      responses:
        '200':
          description: All wallet alerts deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{external_customer_id}/wallets/{wallet_code}/alerts/{code}:
    parameters:
      - $ref: '#/components/parameters/external_customer_id_path'
      - $ref: '#/components/parameters/wallet_code'
      - name: code
        in: path
        description: Unique code of the alert
        required: true
        schema:
          type: string
          example: balance_threshold_alert
    get:
      tags:
        - wallets
      summary: Retrieve a wallet alert
      description: This endpoint enables the retrieval of a specific alert for a wallet.
      operationId: getCustomerWalletAlert
      responses:
        '200':
          description: Wallet alert
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletAlert'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
        - wallets
      summary: Update a wallet alert
      description: This endpoint allows you to update an existing alert for a wallet.
      operationId: updateCustomerWalletAlert
      requestBody:
        description: Update an existing alert for a wallet
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletAlertUpdateInput'
        required: true
      responses:
        '200':
          description: Wallet alert updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletAlert'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
        - wallets
      summary: Delete a wallet alert
      description: This endpoint allows you to delete an existing alert for a wallet.
      operationId: deleteCustomerWalletAlert
      responses:
        '200':
          description: Wallet alert deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletAlert'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{external_customer_id}/current_usage:
    get:
      tags:
        - customers
      summary: Retrieve customer current usage
      description: This endpoint enables the retrieval of the usage-based billing data for a customer within the current period.
      parameters:
        - name: external_customer_id
          in: path
          description: The customer external unique identifier (provided by your own application).
          required: true
          schema:
            type: string
            example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        - name: external_subscription_id
          in: query
          description: The unique identifier of the subscription within your application.
          required: true
          explode: true
          schema:
            type: string
            example: sub_1234567890
        - name: apply_taxes
          in: query
          description: |
            Optional flag to determine if taxes should be applied. Defaults to `true` if not provided or if null.
          required: false
          schema:
            type: boolean
            default: true
            example: true
        - name: charge_id
          in: query
          description: Filter usage to a specific charge by its Lago ID (UUID). Replaces deprecated `filter_by_charge_id`.
          required: false
          schema:
            type: string
            format: uuid
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        - name: charge_code
          in: query
          description: Filter usage to a specific charge by its code. Replaces deprecated `filter_by_charge_code`.
          required: false
          schema:
            type: string
            example: storage
        - name: billable_metric_code
          in: query
          description: Filter usage to a specific billable metric by its code.
          required: false
          schema:
            type: string
            example: storage
        - name: group
          in: query
          description: |
            Filter usage by pricing group. Pass key/value pairs as query parameters, e.g. `group[cloud]=aws`. Replaces deprecated `filter_by_group`.
          required: false
          style: deepObject
          explode: true
          schema:
            type: object
            additionalProperties:
              type: string
            example:
              cloud: aws
        - name: filter_by_charge_id
          in: query
          description: '**Deprecated.** Filter usage to a specific charge by its Lago ID (UUID).'
          required: false
          deprecated: true
          schema:
            type: string
            format: uuid
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        - name: filter_by_charge_code
          in: query
          description: '**Deprecated.** Filter usage to a specific charge by its code.'
          required: false
          deprecated: true
          schema:
            type: string
            example: storage
        - name: filter_by_group
          in: query
          description: |
            **Deprecated.** Filter usage by pricing group. Pass key/value pairs as query parameters, e.g. `filter_by_group[cloud]=aws`.
          required: false
          deprecated: true
          style: deepObject
          explode: true
          schema:
            type: object
            additionalProperties:
              type: string
            example:
              cloud: aws
        - name: full_usage
          in: query
          description: |
            When `true`, returns usage since subscription start instead of the current billing period. Requires one of `charge_id`, `charge_code`, `group` (or their deprecated `filter_by_*` equivalents) to be set.
          required: false
          schema:
            type: boolean
            default: false
            example: true
        - name: filter_by_presentation
          in: query
          description: |
            Filter `presentation_breakdowns` by a JSON-encoded array 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
          schema:
            type: string
            example: '["engineering", "operations"]'
      operationId: findCustomerCurrentUsage
      responses:
        '200':
          description: Customer usage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerUsage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{external_customer_id}/projected_usage:
    get:
      tags:
        - customers
      summary: Retrieve customer current and projected usage
      description: This endpoint enables the retrieval of the usage-based billing data for a customer within the current period. It also returns the projected usage for the current period based on the current usage.
      parameters:
        - name: external_customer_id
          in: path
          description: The customer external unique identifier (provided by your own application).
          required: true
          schema:
            type: string
            example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        - name: external_subscription_id
          in: query
          description: The unique identifier of the subscription within your application.
          required: true
          explode: true
          schema:
            type: string
            example: sub_1234567890
        - name: apply_taxes
          in: query
          description: |
            Optional flag to determine if taxes should be applied. Defaults to `true` if not provided or if null.
          required: false
          schema:
            type: boolean
            default: true
            example: true
      operationId: findCustomerProjectedUsage
      responses:
        '200':
          description: Customer usage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerProjectedUsage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{external_customer_id}/past_usage:
    get:
      tags:
        - customers
      summary: Retrieve customer past usage
      description: This endpoint enables the retrieval of the usage-based billing data for a customer within past periods.
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - name: external_customer_id
          in: path
          description: The customer external unique identifier (provided by your own application).
          required: true
          schema:
            type: string
            example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        - name: external_subscription_id
          in: query
          description: The unique identifier of the subscription within your application.
          required: true
          explode: true
          schema:
            type: string
            example: sub_1234567890
        - name: billable_metric_code
          in: query
          description: Billable metric code filter to apply to the charge usage
          required: false
          explode: true
          schema:
            type: string
            example: cpu
        - name: periods_count
          in: query
          description: Number of past billing period to returns in the result
          required: false
          explode: true
          schema:
            type: integer
            example: 5
      operationId: findAllCustomerPastUsage
      responses:
        '200':
          description: Customer past usage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerPastUsage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /customers/{external_customer_id}/checkout_url:
    post:
      tags:
        - customers
      summary: Generate a Customer Payment Provider Checkout URL
      description: This endpoint regenerates the Payment Provider Checkout URL of a Customer.
      parameters:
        - name: external_customer_id
          in: path
          description: The customer external unique identifier (provided by your own application).
          required: true
          schema:
            type: string
            example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
      operationId: generateCustomerCheckoutURL
      responses:
        '200':
          description: Customer Checkout URL
          content:
            application/json:
              schema:
                type: object
                required:
                  - customer
                properties:
                  customer:
                    $ref: '#/components/schemas/CustomerCheckoutUrl'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /customers/{external_customer_id}/payment_methods:
    get:
      tags:
        - payment_methods
      summary: List all customer payment methods
      description: This endpoint retrieves all payment methods of a Customer.
      operationId: findAllCustomersPaymentMethods
      parameters:
        - $ref: '#/components/parameters/external_customer_id_path'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: List of customer's payment methods
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethodsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{external_customer_id}/payment_methods/{lago_id}/set_as_default:
    parameters:
      - name: lago_id
        in: path
        description: The payment method unique identifier, created by Lago.
        required: true
        schema:
          type: string
          format: uuid
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
      - $ref: '#/components/parameters/external_customer_id_path'
    put:
      tags:
        - payment_methods
      operationId: paymentMethodSetAsDefault
      summary: Set the payment method as default
      description: Use the payment method as default when not selected a payment method
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethod'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{external_customer_id}/payment_methods/{lago_id}:
    parameters:
      - name: lago_id
        in: path
        description: The payment method unique identifier, created by Lago.
        required: true
        schema:
          type: string
          format: uuid
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
      - $ref: '#/components/parameters/external_customer_id_path'
    delete:
      tags:
        - payment_methods
      summary: Delete a payment method
      description: This endpoint deletes a specific payment method for a customer.
      operationId: destroyPaymentMethod
      responses:
        '200':
          description: Payment method deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethod'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /events:
    post:
      tags:
        - events
      summary: Send usage events
      description: This endpoint is used for transmitting usage measurement events to either a designated customer or a specific subscription.
      operationId: createEvent
      requestBody:
        description: Event payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventInput'
        required: true
      responses:
        '200':
          description: Event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventCreated'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - events
      summary: List all events
      description: This endpoint is used for retrieving all events.
      operationId: findAllEvents
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - $ref: '#/components/parameters/external_subscription_id'
        - name: code
          in: query
          description: Filter events by its code.
          required: false
          explode: true
          schema:
            type: string
            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.
          required: false
          explode: true
          schema:
            type: boolean
            example: true
        - name: timestamp_from
          in: query
          description: Filter events by timestamp starting from a specific date.
          required: false
          explode: true
          schema:
            type: string
            format: date-time
            example: '2022-08-08T00:00:00Z'
        - name: timestamp_to
          in: query
          description: Filter events by timestamp up to a specific date.
          required: false
          explode: true
          schema:
            type: string
            format: date-time
            example: '2022-08-08T00:00:00Z'
      responses:
        '200':
          description: Events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /events/batch:
    post:
      tags:
        - events
      summary: Batch multiple events
      description: This endpoint can be used to send a batch of usage records. Each request may include up to 100 events.
      operationId: createBatchEvents
      requestBody:
        description: Batch events payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventBatchInput'
        required: true
      responses:
        '200':
          description: Event received
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsCreated'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /events/estimate_fees:
    post:
      tags:
        - events
      summary: Estimate fees for a pay in advance charge
      description: Estimate the fees that would be created after reception of an event for a billable metric attached to one or multiple pay in advance charges
      operationId: eventEstimateFees
      requestBody:
        description: Event estimate payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventEstimateFeesInput'
        required: true
      responses:
        '200':
          description: Fees estimate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fees'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /events/estimate_instant_fees:
    post:
      tags:
        - events
      summary: Estimate instant fees for a pay in advance charge
      description: Estimate the fees that would be created after reception of an event for a billable metric attached to one or multiple pay in advance standard or percentage charges
      operationId: eventEstimateInstantFees
      requestBody:
        description: Event estimate instant payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventEstimateInstantFeesInput'
        required: true
      responses:
        '200':
          description: Fees estimate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeesEstimate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /events/batch_estimate_instant_fees:
    post:
      tags:
        - events
      summary: Batch estimate instant fees for a pay in advance charge
      description: Estimate the fees that would be created after reception of an event for a billable metric attached to one or multiple pay in advance standard or percentage charges
      operationId: eventBatchEstimateInstantFees
      requestBody:
        description: Batch event estimate instant payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventBatchEstimateInstantFeesInput'
        required: true
      responses:
        '200':
          description: Fees estimate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeesEstimate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /events/{transaction_id}:
    parameters:
      - name: transaction_id
        in: path
        description: This field represents the unique identifier sent for this specific event (must be URL encoded).
        required: true
        schema:
          type: string
          example: transaction_1234567890
    get:
      tags:
        - events
      summary: Retrieve a specific event
      description: |
        This endpoint is used for retrieving a specific usage measurement event that has been sent to a customer or a subscription.

        Note that transaction_id is unique per external_subscription_id so multiple subscriptions can share the same transaction_id. This endpoint will only return the first event found with the given transaction_id.

        WARNING: If your Lago organization is configured to use the Clickhouse-based event pipeline, multiple events can share the same `transaction_id` (with different timestamps). This endpoint will only return the first event found.
      operationId: findEvent
      responses:
        '200':
          description: Event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /fees:
    get:
      tags:
        - fees
      summary: List all fees
      description: This endpoint is used for retrieving all fees that has been issued.
      operationId: findAllFees
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - $ref: '#/components/parameters/external_customer_id'
        - $ref: '#/components/parameters/external_subscription_id'
        - name: event_transaction_id
          in: query
          description: Filter results by event transaction ID
          required: false
          explode: true
          schema:
            type: string
            example: et_12345678
        - name: currency
          in: query
          description: Filter results by fee"s currency.
          required: false
          explode: true
          schema:
            allOf:
              - $ref: '#/components/schemas/Currency'
              - example: USD
        - name: fee_type
          in: query
          description: The fee type. Possible values are `add-on`, `charge`, `credit`, `subscription` or "commitment".
          required: false
          explode: true
          schema:
            type: string
            enum:
              - charge
              - add_on
              - subscription
              - credit
              - commitment
            example: charge
        - name: billable_metric_code
          in: query
          description: Filter results by the `code` of the billable metric attached to the fee. Only applies to `charge` types.
          required: false
          explode: true
          schema:
            type: string
            example: bm_code
        - name: payment_status
          in: query
          description: Indicates the payment status of the fee. It represents the current status of the payment associated with the fee. The possible values for this field are `pending`, `succeeded`, `failed` and refunded`.
          required: false
          explode: true
          schema:
            type: string
            enum:
              - pending
              - succeeded
              - failed
              - refunded
            example: succeeded
        - name: created_at_from
          in: query
          description: Filter results created after creation date and time in UTC.
          required: false
          explode: true
          schema:
            type: string
            example: '2023-03-28T12:21:51Z'
            format: date-time
        - name: created_at_to
          in: query
          description: Filter results created before creation date and time in UTC.
          required: false
          explode: true
          schema:
            type: string
            example: '2023-03-28T12:21:51Z'
            format: date-time
        - name: succeeded_at_from
          in: query
          description: Filter results with payment success after creation date and time in UTC.
          required: false
          explode: true
          schema:
            type: string
            example: '2023-03-28T12:21:51Z'
            format: date-time
        - name: succeeded_at_to
          in: query
          description: Filter results with payment success after creation date and time in UTC.
          required: false
          explode: true
          schema:
            type: string
            example: '2023-03-28T12:21:51Z'
            format: date-time
        - name: failed_at_from
          in: query
          description: Filter results with payment failure after creation date and time in UTC.
          required: false
          explode: true
          schema:
            type: string
            example: '2023-03-28T12:21:51Z'
            format: date-time
        - name: failed_at_to
          in: query
          description: Filter results with payment failure after creation date and time in UTC.
          required: false
          explode: true
          schema:
            type: string
            example: '2023-03-28T12:21:51Z'
            format: date-time
        - name: refunded_at_from
          in: query
          description: Filter results with payment refund after creation date and time in UTC.
          required: false
          explode: true
          schema:
            type: string
            example: '2023-03-28T12:21:51Z'
            format: date-time
        - name: refunded_at_to
          in: query
          description: Filter results with payment refund after creation date and time in UTC.
          required: false
          explode: true
          schema:
            type: string
            example: '2023-03-28T12:21:51Z'
            format: date-time
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeesPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /fees/{lago_id}:
    parameters:
      - name: lago_id
        in: path
        description: Unique identifier assigned to the fee within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the fee's record within the Lago system.
        required: true
        schema:
          type: string
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
    get:
      tags:
        - fees
      summary: Retrieve a specific fee
      description: This endpoint is used for retrieving a specific fee that has been issued.
      operationId: findFee
      responses:
        '200':
          description: Fee
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fee'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
        - fees
      summary: Update a fee
      description: This endpoint is used for updating a specific fee that has been issued.
      operationId: updateFee
      requestBody:
        description: Fee payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeeUpdateInput'
      responses:
        '200':
          description: Fee updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fee'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/NotAllowed'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
        - fees
      summary: Delete a fee
      description: This endpoint is used for deleting a specific fee that has not yet been invoiced
      operationId: deleteFee
      responses:
        '200':
          description: Fee deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fee'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/NotAllowed'
  /invoices:
    post:
      tags:
        - invoices
      summary: Create a one-off invoice
      description: This endpoint is used for issuing a one-off invoice.
      operationId: createInvoice
      requestBody:
        description: Invoice payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceOneOffCreateInput'
        required: true
      responses:
        '200':
          description: Invoice created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - invoices
      summary: List all invoices
      description: This endpoint is used for retrieving all invoices.
      operationId: findAllInvoices
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - $ref: '#/components/parameters/external_customer_id'
        - name: amount_from
          in: query
          description: Filter invoices of at least a specific amount. This parameter must be defined in cents to ensure consistent handling for all currency types.
          required: false
          explode: true
          schema:
            type: integer
            example: 9000
        - name: amount_to
          in: query
          description: Filter invoices up to a specific amount. This parameter must be defined in cents to ensure consistent handling for all currency types.
          required: false
          explode: true
          schema:
            type: integer
            example: 100000
        - name: issuing_date_from
          in: query
          description: Filter invoices starting from a specific date.
          required: false
          explode: true
          schema:
            type: string
            format: date
            example: '2022-07-08'
        - name: issuing_date_to
          in: query
          description: Filter invoices up to a specific date.
          required: false
          explode: true
          schema:
            type: string
            format: date
            example: '2022-08-09'
        - name: statuses[]
          in: query
          description: Filter invoices by statuses. Possible values are `draft`, `failed`, `finalized`, `pending` and `voided`.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - draft
                - finalized
                - failed
                - pending
                - voided
        - name: payment_statuses[]
          in: query
          description: Filter invoices by payment statuses. Possible values are `pending`, `failed` or `succeeded`.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - pending
                - failed
                - succeeded
        - name: payment_overdue
          in: query
          description: Filter invoices by payment_overdue. Possible values are `true` or `false`.
          required: false
          explode: true
          schema:
            type: boolean
            example: true
        - name: search_term
          in: query
          description: Search invoices by id, number, customer name, customer external_id or customer email.
          required: false
          explode: true
          schema:
            type: string
            example: Jane
        - name: currency
          in: query
          description: Filter invoices by currency. Possible values ISO 4217 currency codes.
          required: false
          explode: true
          schema:
            type: string
            example: EUR
        - name: payment_dispute_lost
          in: query
          description: Filter invoices with a payment dispute lost. Possible values are `true` or `false`.
          required: false
          explode: true
          schema:
            type: boolean
            example: true
        - name: invoice_type
          in: query
          description: Filter invoices by invoice type. Possible values are `subscription`, `add_on`, `credit`, `one_off`, `advance_charges` or `progressive_billing`.
          required: false
          explode: true
          schema:
            type: string
            enum:
              - subscription
              - add_on
              - credit
              - one_off
              - advance_charges
              - progressive_billing
        - name: self_billed
          in: query
          description: Filter invoices by self billed. Possible values are `true` or `false`.
          required: false
          explode: true
          schema:
            type: boolean
            example: true
        - name: billing_entity_codes[]
          in: query
          description: Filter invoices by billing entity codes. Possible values are the billing entity codes you have created.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
            example:
              - acme_corp
              - foo_bar
        - name: metadata[key]
          in: query
          description: Filter invoices by metadata. Replace `key` with the actual metadata key you want to match, and provide the corresponding value. Providing empty value will search for invoice without given metadata key. For example, `metadata[color]=blue`.
          required: false
          explode: true
          schema:
            type: string
            example: someValue
      responses:
        '200':
          description: Invoices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoicesPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /invoices/{lago_id}:
    parameters:
      - $ref: '#/components/parameters/lago_invoice_id'
    put:
      tags:
        - invoices
      summary: Update an invoice
      description: This endpoint is used for updating an existing invoice.
      operationId: updateInvoice
      requestBody:
        description: Update an existing invoice
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceUpdateInput'
        required: true
      responses:
        '200':
          description: Invoice updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - invoices
      summary: Retrieve an invoice
      description: This endpoint is used for retrieving a specific invoice that has been issued.
      operationId: findInvoice
      responses:
        '200':
          description: Invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - invoices
      summary: Delete a draft invoice
      description: 'This endpoint is used for permanently deleting a `draft` invoice. Deleting a draft invoice removes it entirely: it never becomes accounts receivable, consumes no invoice number, and disappears from every list, export, and analytics surface. Only invoices in the `draft` status can be deleted; for a `finalized` invoice, void it instead.'
      operationId: deleteInvoice
      responses:
        '200':
          description: Invoice deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/NotAllowed'
  /invoices/{lago_id}/download:
    post:
      tags:
        - invoices
      summary: Download an invoice PDF
      parameters:
        - $ref: '#/components/parameters/lago_invoice_id'
      description: This endpoint is used for downloading a specific invoice PDF document.
      operationId: downloadInvoice
      responses:
        '200':
          description: Invoice PDF
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /invoices/{lago_id}/finalize:
    put:
      tags:
        - invoices
      summary: Finalize a draft invoice
      description: This endpoint is used for finalizing a draft invoice.
      parameters:
        - $ref: '#/components/parameters/lago_invoice_id'
      operationId: finalizeInvoice
      responses:
        '200':
          description: Invoice finalized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /invoices/{lago_id}/lose_dispute:
    post:
      tags:
        - invoices
      summary: Mark an invoice payment dispute as lost
      description: This endpoint is used for setting invoice's payment dispute as lost.
      parameters:
        - $ref: '#/components/parameters/lago_invoice_id'
      operationId: loseDisputeInvoice
      responses:
        '200':
          description: Invoice payment dispute lost
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/NotAllowed'
  /invoices/{lago_id}/refresh:
    put:
      tags:
        - invoices
      summary: Refresh a draft invoice
      description: This endpoint is used for refreshing a draft invoice.
      parameters:
        - $ref: '#/components/parameters/lago_invoice_id'
      operationId: refreshInvoice
      responses:
        '200':
          description: Invoice refreshed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /invoices/{lago_id}/retry:
    post:
      tags:
        - invoices
      summary: Retry generation of a failed invoice
      description: This endpoint is used for retrying to generate a failed invoice.
      parameters:
        - $ref: '#/components/parameters/lago_invoice_id'
      operationId: retryInvoice
      responses:
        '200':
          description: Invoice generation has been retried
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /invoices/{lago_id}/payment_url:
    post:
      tags:
        - invoices
      summary: Generate a payment URL
      description: This endpoint generates a checkout link for a specific invoice.
      parameters:
        - $ref: '#/components/parameters/lago_invoice_id'
      operationId: invoicePaymentUrl
      responses:
        '200':
          description: Payment URL has been generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoicePaymentUrl'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /invoices/preview:
    post:
      tags:
        - invoices
      summary: Create an invoice preview
      description: This endpoint is used for generating invoice preview.
      operationId: invoicePreview
      requestBody:
        description: Invoice preview payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoicePreviewInput'
        required: true
      responses:
        '200':
          description: Invoice preview created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /invoices/{lago_id}/retry_payment:
    post:
      tags:
        - invoices
      summary: Retry an invoice payment
      description: This endpoint resends an invoice for collection and retry a payment.
      parameters:
        - $ref: '#/components/parameters/lago_invoice_id'
      operationId: retryPayment
      requestBody:
        description: Payment method to use for the retry (optional)
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                payment_method:
                  $ref: '#/components/schemas/PaymentMethodReference'
      responses:
        '200':
          description: Invoice payment retried
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/NotAllowed'
  /invoices/{lago_id}/void:
    post:
      tags:
        - invoices
      summary: Void an invoice
      description: |-
        This endpoint is used for voiding an invoice.
        • When no body parameters are provided, the invoice can be voided only if it is in a `finalized` status and its payment status is NOT `succeeded`.
        • When `generate_credit_note` is provided (optionally with `refund_amount` and/or `credit_amount`), this validation is bypassed: the invoice is forcibly voided and a credit note is generated. If the specified refund/credit amounts do not cover the full invoice total, the remainder is issued on a second credit note that is created and immediately voided.
      parameters:
        - $ref: '#/components/parameters/lago_invoice_id'
      requestBody:
        description: Void invoice payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceVoidInput'
        required: false
      operationId: voidInvoice
      responses:
        '200':
          description: Invoice voided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /organizations:
    put:
      tags:
        - organizations
      summary: Update your organization
      description: This endpoint is used to update your own organization's settings.
      operationId: updateOrganization
      requestBody:
        description: Update an existing organization
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationUpdateInput'
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /payment_receipts:
    get:
      tags:
        - payment_receipts
      summary: List all payment receipts
      description: This endpoint is used to list all existing payment receipts.
      operationId: findAllPaymentReceipts
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - name: invoice_id
          in: query
          description: Filter payment receipts by invoice id.
          required: false
          explode: true
          schema:
            type: string
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
      responses:
        '200':
          description: PaymentReceipts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentReceiptsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /payment_receipts/{lago_id}:
    parameters:
      - name: lago_id
        in: path
        description: Payment receipt ID
        required: true
        schema:
          type: string
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
    get:
      tags:
        - payment_receipts
      summary: Retrieve a payment receipt
      description: This endpoint retrieves a specific payment receipt.
      operationId: findPaymentReceipt
      responses:
        '200':
          description: Payment receipt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentReceipt'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /payment_requests:
    post:
      tags:
        - payment_requests
      summary: Create a payment request
      description: This endpoint is used to create a payment request to collect payments of overdue invoices of a given customer
      operationId: createPaymentRequest
      requestBody:
        description: PaymentRequest payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequestCreateInput'
        required: true
      responses:
        '200':
          description: PaymentRequest created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequest'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - payment_requests
      summary: List all payment requests
      description: This endpoint is used to list all existing payment requests.
      operationId: findAllPaymentRequests
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - $ref: '#/components/parameters/currency'
        - $ref: '#/components/parameters/external_customer_id'
        - $ref: '#/components/parameters/payment_status'
        - name: billing_entity_codes[]
          in: query
          description: Filter payment requests by billing entity codes.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
            example:
              - billing_entity_code_1
              - billing_entity_code_2
      responses:
        '200':
          description: PaymentRequests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequestsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /payment_requests/{lago_id}:
    parameters:
      - name: lago_id
        in: path
        description: Unique identifier of the payment request.
        required: true
        schema:
          type: string
          format: uuid
          example: f4a842d6-4bde-11ec-81d3-0242ac130003
    get:
      tags:
        - payment_requests
      summary: Retrieve a payment request
      description: This endpoint retrieves a specific payment request by its ID.
      operationId: findPaymentRequest
      responses:
        '200':
          description: Payment request details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequestObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /payments:
    post:
      tags:
        - payments
      summary: Create a payment
      description: This endpoint is used to create a manual payment
      operationId: createPayment
      requestBody:
        description: Payment payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCreateInput'
        required: true
      responses:
        '200':
          description: Payment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - payments
      summary: List all payments
      description: This endpoint is used to list all payments
      operationId: findAllPayments
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - $ref: '#/components/parameters/external_customer_id'
        - name: invoice_id
          in: query
          description: Unique identifier assigned to the invoice within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the invoice's record within the Lago system.
          required: false
          schema:
            type: string
            format: uuid
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
      responses:
        '200':
          description: Payments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /payments/{lago_id}:
    parameters:
      - name: lago_id
        in: path
        description: Unique identifier of the payment.
        required: true
        schema:
          type: string
          format: uuid
          example: f4a842d6-4bde-11ec-81d3-0242ac130003
    get:
      tags:
        - payments
      summary: Retrieve a payment
      description: This endpoint retrieves a specific payment by its ID.
      operationId: findPayment
      responses:
        '200':
          description: Payment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /plans:
    post:
      tags:
        - plans
      summary: Create a plan
      description: This endpoint creates a plan with subscription and usage-based charges. It supports flexible billing cadence (in-advance or in-arrears) and allows for both recurring and metered charges.
      operationId: createPlan
      requestBody:
        description: Plan payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanCreateInput'
        required: true
      responses:
        '200':
          description: Plan created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - plans
      summary: List all plans
      description: This endpoint retrieves all existing plans.
      operationId: findAllPlans
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: Plans
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlansPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /plans/{code}:
    parameters:
      - name: code
        in: path
        description: The code of the plan. It serves as a unique identifier associated with a particular plan. The code is typically used for internal or system-level identification purposes, like assigning a subscription, for instance.
        required: true
        schema:
          type: string
          example: startup
    put:
      tags:
        - plans
      summary: Update a plan
      description: This endpoint updates a specific plan with subscription and usage-based charges. It supports flexible billing cadence (in-advance or in-arrears) and allows for both recurring and metered charges.
      operationId: updatePlan
      requestBody:
        description: Plan payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanUpdateInput'
        required: true
      responses:
        '200':
          description: Plan updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - plans
      summary: Retrieve a plan
      description: This endpoint retrieves a specific plan.
      operationId: findPlan
      responses:
        '200':
          description: Plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - plans
      summary: Delete a plan
      description: This endpoint deletes a specific plan. Note that this plan could be associated with active subscriptions.
      operationId: destroyPlan
      responses:
        '200':
          description: Plan deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /plans/{code}/entitlements:
    parameters:
      - name: code
        in: path
        description: Code of the existing plan.
        required: true
        schema:
          type: string
          example: startup
    post:
      tags:
        - entitlements
      summary: Create an entitlement
      description: This endpoint creates new entitlements by adding features to a plan. Note that all existing entitlements will be deleted and replaced by the ones provided. To add a new entitlement without removing the existing ones, use PATCH. The feature must exist and all privileges must be valid for the feature.
      operationId: createEntitlement
      requestBody:
        description: Entitlement payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementUpdateInput'
        required: true
      responses:
        '200':
          description: Entitlement created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanEntitlements'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - entitlements
      summary: List all entitlements
      description: This endpoint retrieves all entitlements for a specific plan.
      operationId: findAllEntitlements
      responses:
        '200':
          description: List of entitlements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanEntitlements'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
        - entitlements
      summary: Partial update of an entitlement
      description: This accepts a list of entitlements to update. If the feature isn't part of the plan yet, it's added with all the privileges from the payload. If the feature is already part of the plan, the privilege and values are updated or added. All privileges must be valid for the feature. All features  and privileges not part of the payload are left untouched. To remove privileges or features, use the DELETE endpoints.
      operationId: updateEntitlement
      requestBody:
        description: Entitlement payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementUpdateInput'
        required: true
      responses:
        '200':
          description: Entitlement updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanEntitlements'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /plans/{code}/entitlements/{feature_code}:
    parameters:
      - name: code
        in: path
        description: Code of the existing plan.
        required: true
        schema:
          type: string
          example: startup
      - name: feature_code
        in: path
        description: Code of the existing feature.
        required: true
        schema:
          type: string
          example: seats
    get:
      tags:
        - entitlements
      summary: Retrieve an entitlement
      description: This endpoint retrieves a specific entitlement for a plan.
      operationId: findEntitlement
      responses:
        '200':
          description: Entitlement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanEntitlement'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - entitlements
      summary: Delete an entitlement
      description: This endpoint deletes an existing entitlement by removing the feature from the plan.
      operationId: destroyEntitlement
      responses:
        '200':
          description: Entitlement deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanEntitlement'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /plans/{code}/entitlements/{feature_code}/privileges/{privilege_code}:
    parameters:
      - name: code
        in: path
        description: Code of the existing plan.
        required: true
        schema:
          type: string
          example: startup
      - name: feature_code
        in: path
        description: Code of the existing feature.
        required: true
        schema:
          type: string
          example: seats
      - name: privilege_code
        in: path
        description: Code of the privilege to remove from the entitlement.
        required: true
        schema:
          type: string
          example: max_admins
    delete:
      tags:
        - entitlements
      summary: Remove a privilege from an entitlement
      description: This endpoint removes a specific privilege and its value from an entitlement. The privilege remains untouched on the original feature.
      operationId: removeEntitlementPrivilege
      responses:
        '200':
          description: Entitlement with privilege removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanEntitlement'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /plans/{code}/metadata:
    post:
      tags:
        - plans
      summary: Replace plan metadata
      description: |-
        This endpoint replaces all existing metadata on a plan with the provided key-value pairs.
        Any existing metadata keys not included in the request will be removed.
      parameters:
        - name: code
          in: path
          description: The code of the plan.
          required: true
          schema:
            type: string
            example: startup
      operationId: replacePlanMetadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanMetadataResponse'
      responses:
        '200':
          description: Plan metadata replaced
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanMetadataResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    patch:
      tags:
        - plans
      summary: Merge plan metadata
      description: |-
        This endpoint merges the provided metadata with existing metadata on the plan.
        Existing keys not in the request are preserved. New keys are added, existing keys are updated.
      parameters:
        - name: code
          in: path
          description: The code of the plan.
          required: true
          schema:
            type: string
            example: startup
      operationId: mergePlanMetadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanMetadataResponse'
      responses:
        '200':
          description: Plan metadata merged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanMetadataResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
        - plans
      summary: Delete all plan metadata
      description: This endpoint removes all metadata from a plan.
      parameters:
        - name: code
          in: path
          description: The code of the plan.
          required: true
          schema:
            type: string
            example: startup
      operationId: deleteAllPlanMetadata
      responses:
        '200':
          description: Plan metadata deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanMetadataResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /plans/{code}/metadata/{key}:
    delete:
      tags:
        - plans
      summary: Delete a metadata key
      description: This endpoint removes a single metadata key from a plan.
      parameters:
        - name: code
          in: path
          description: The code of the plan.
          required: true
          schema:
            type: string
            example: startup
        - name: key
          in: path
          description: The metadata key to delete.
          required: true
          schema:
            type: string
            example: external_id
      operationId: deletePlanMetadataKey
      responses:
        '200':
          description: Metadata key deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanMetadataResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /plans/{code}/charges:
    parameters:
      - $ref: '#/components/parameters/plan_code'
    post:
      tags:
        - plans
      summary: Create a charge
      description: This endpoint creates a new charge for a specific plan.
      operationId: createPlanCharge
      requestBody:
        description: Charge payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeCreateInput'
        required: true
      responses:
        '200':
          description: Charge created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Charge'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - plans
      summary: List all charges for a plan
      description: This endpoint retrieves all charges for a specific plan.
      operationId: findAllPlanCharges
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: List of charges
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargesPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /plans/{code}/charges/{charge_code}:
    parameters:
      - $ref: '#/components/parameters/plan_code'
      - $ref: '#/components/parameters/charge_code'
    get:
      tags:
        - plans
      summary: Retrieve a charge
      description: This endpoint retrieves a specific charge for a plan.
      operationId: findPlanCharge
      responses:
        '200':
          description: Charge
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Charge'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
        - plans
      summary: Update a charge
      description: This endpoint updates a specific charge for a plan.
      operationId: updatePlanCharge
      requestBody:
        description: Charge payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeUpdateInput'
        required: true
      responses:
        '200':
          description: Charge updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Charge'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
        - plans
      summary: Delete a charge
      description: This endpoint deletes a specific charge from a plan.
      operationId: destroyPlanCharge
      requestBody:
        description: Charge delete payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeDeleteInput'
      responses:
        '200':
          description: Charge deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Charge'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /plans/{code}/charges/{charge_code}/filters:
    parameters:
      - $ref: '#/components/parameters/plan_code'
      - $ref: '#/components/parameters/charge_code'
    post:
      tags:
        - plans
      summary: Create a charge filter
      description: This endpoint creates a new filter for a specific charge.
      operationId: createPlanChargeFilter
      requestBody:
        description: Charge filter payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeFilterCreateInput'
        required: true
      responses:
        '200':
          description: Charge filter created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeFilterResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - plans
      summary: List all filters for a charge
      description: This endpoint retrieves all filters for a specific charge.
      operationId: findAllPlanChargeFilters
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: List of charge filters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeFiltersPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /plans/{code}/charges/{charge_code}/filters/{filter_id}:
    parameters:
      - $ref: '#/components/parameters/plan_code'
      - $ref: '#/components/parameters/charge_code'
      - $ref: '#/components/parameters/charge_filter_id'
    get:
      tags:
        - plans
      summary: Retrieve a charge filter
      description: This endpoint retrieves a specific filter for a charge.
      operationId: findPlanChargeFilter
      responses:
        '200':
          description: Charge filter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeFilterResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
        - plans
      summary: Update a charge filter
      description: This endpoint updates a specific filter for a charge.
      operationId: updatePlanChargeFilter
      requestBody:
        description: Charge filter payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeFilterUpdateInput'
        required: true
      responses:
        '200':
          description: Charge filter updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeFilterResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
        - plans
      summary: Delete a charge filter
      description: This endpoint deletes a specific filter from a charge.
      operationId: destroyPlanChargeFilter
      requestBody:
        description: Charge filter delete payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeFilterDeleteInput'
      responses:
        '200':
          description: Charge filter deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeFilterResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /plans/{code}/fixed_charges:
    parameters:
      - $ref: '#/components/parameters/plan_code'
    post:
      tags:
        - plans
      summary: Create a fixed charge
      description: This endpoint creates a new fixed charge for a specific plan.
      operationId: createPlanFixedCharge
      requestBody:
        description: Fixed charge payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FixedChargeCreateInput'
        required: true
      responses:
        '200':
          description: Fixed charge created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FixedCharge'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - plans
      summary: List all fixed charges for a plan
      description: This endpoint retrieves all fixed charges for a specific plan.
      operationId: findAllPlanFixedCharges
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: List of fixed charges
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FixedChargesPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /plans/{code}/fixed_charges/{fixed_charge_code}:
    parameters:
      - $ref: '#/components/parameters/plan_code'
      - $ref: '#/components/parameters/fixed_charge_code'
    get:
      tags:
        - plans
      summary: Retrieve a fixed charge
      description: This endpoint retrieves a specific fixed charge for a plan.
      operationId: findPlanFixedCharge
      responses:
        '200':
          description: Fixed charge
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FixedCharge'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
        - plans
      summary: Update a fixed charge
      description: This endpoint updates a specific fixed charge for a plan.
      operationId: updatePlanFixedCharge
      requestBody:
        description: Fixed charge payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FixedChargeUpdateInput'
        required: true
      responses:
        '200':
          description: Fixed charge updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FixedCharge'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
        - plans
      summary: Delete a fixed charge
      description: This endpoint deletes a specific fixed charge from a plan.
      operationId: destroyPlanFixedCharge
      requestBody:
        description: Fixed charge delete payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FixedChargeDeleteInput'
      responses:
        '200':
          description: Fixed charge deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FixedCharge'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /subscriptions:
    post:
      tags:
        - subscriptions
      summary: Assign a plan to a customer
      description: This endpoint assigns a plan to a customer, creating or modifying a subscription. Ideal for initial subscriptions or plan changes (upgrades/downgrades).
      operationId: createSubscription
      requestBody:
        description: Subscription payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionCreateInput'
        required: true
      responses:
        '200':
          description: Subscription created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionExtended'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - subscriptions
      summary: List all subscriptions
      description: This endpoint retrieves all active subscriptions.
      operationId: findAllSubscriptions
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - $ref: '#/components/parameters/currency'
        - name: external_customer_id
          in: query
          description: The customer external unique identifier (provided by your own application)
          required: false
          schema:
            type: string
            example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        - name: plan_code
          in: query
          description: The unique code representing the plan to be attached to the customer. This code must correspond to the code property of one of the active plans.
          required: false
          schema:
            type: string
            example: premium
        - name: status[]
          in: query
          description: 'If the field is not defined, Lago will return only `active` subscriptions. However, if you wish to fetch subscriptions by different status you can define them in a status[] query param. Available filter values: `pending`, `canceled`, `terminated`, `active`.'
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - active
                - canceled
                - pending
                - terminated
            example:
              - active
              - pending
        - name: billing_entity_codes[]
          in: query
          description: Filter subscriptions by billing entity codes.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
            example:
              - billing_entity_code_1
              - billing_entity_code_2
      responses:
        '200':
          description: List of subscriptions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /subscriptions/{external_id}:
    parameters:
      - name: external_id
        in: path
        description: External ID of the existing subscription
        required: true
        schema:
          type: string
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
    get:
      tags:
        - subscriptions
      summary: Retrieve a subscription
      description: This endpoint retrieves a specific subscription.
      operationId: findSubscription
      parameters:
        - name: status
          in: query
          description: |
            By default, this endpoint only return `active` subscriptions. If you want to retrieve a subscription with a different `status`, you can specify it here.

            _Note: As there may exists multiple `canceled` or `terminated` subscribtions for the same `external_id`, it is recommended to use the "List all subscriptions" endpoint to retrieve those subscriptions._
          required: false
          schema:
            type: string
            enum:
              - active
              - terminated
              - pending
              - canceled
            example: active
            default: active
      responses:
        '200':
          description: Subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionExtended'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
        - subscriptions
      summary: Update a subscription
      description: This endpoint allows you to update a subscription.
      operationId: updateSubscription
      requestBody:
        description: Update an existing subscription
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionUpdateInput'
        required: true
      parameters:
        - name: status
          in: query
          description: |
            By default, this endpoint only return `active` subscriptions. If you want to update a subscription with a different `status`, you can specify it here.
          required: false
          schema:
            type: string
            enum:
              - active
              - pending
            example: active
            default: active
      responses:
        '200':
          description: Subscription updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
        - subscriptions
      summary: Terminate a subscription
      description: This endpoint allows you to terminate a subscription.
      operationId: destroySubscription
      parameters:
        - name: status
          in: query
          description: If the field is not defined, Lago will terminate only `active` subscriptions. However, if you wish to cancel a `pending` subscription, please ensure that you include `status=pending` in your request.
          required: false
          explode: true
          schema:
            type: string
            example: pending
        - name: on_termination_credit_note
          in: query
          description: |
            When a pay-in-advance subscription is terminated before the end of its billing period, we generate a credit note for the unused subscription time by default.
            This field allows you to control the behavior of the credit note generation:

            - `credit`: A credit note is generated for the unused subscription time. The unused amount is credited back to the customer.
            - `refund`: A credit note is generated for the unused subscription time. If the invoice is paid or partially paid, the unused paid amount is refunded; any unpaid unused amount is credited back to the customer.
            - `skip`: No credit note is generated for the unused subscription time.

            _Note: This field is only applicable to pay-in-advance plans and is ignored for pay-in-arrears plans._
          required: false
          schema:
            type: string
            enum:
              - credit
              - refund
              - skip
            example: credit
        - name: on_termination_invoice
          in: query
          description: |
            When a subscription is terminated before the end of its billing period, we generate an invoice for the unbilled usage.
            This field allows you to control the behavior of the invoice generation:

            - `generate`: An invoice is generated for the unbilled usage.
            - `skip`: No invoice is generated for the unbilled usage.
          required: false
          schema:
            type: string
            enum:
              - generate
              - skip
            example: generate
      responses:
        '200':
          description: Subscription terminated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /subscriptions/{external_id}/lifetime_usage:
    parameters:
      - name: external_id
        in: path
        description: External ID of the existing subscription
        required: true
        schema:
          type: string
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
    get:
      tags:
        - subscriptions
      summary: Retrieve subscription lifetime usage
      description: This endpoint enables the retrieval of the lifetime usage of a subscription.
      operationId: getSubscriptionLifetimeUsage
      responses:
        '200':
          description: Subscription lifetime usage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LifetimeUsage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
        - subscriptions
      summary: Update a subscription lifetime usage
      description: This endpoint allows you to update the lifetime usage of a subscription.
      operationId: updateSubscriptionLifetimeUsage
      requestBody:
        description: Update the lifetime usage of a subscription
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LifetimeUsageInput'
        required: true
      responses:
        '200':
          description: Subscription lifetime usage updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LifetimeUsage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /subscriptions/{external_id}/alerts:
    parameters:
      - name: external_id
        in: path
        description: External ID of the existing subscription
        required: true
        schema:
          type: string
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
    get:
      tags:
        - subscriptions
      summary: List subscription alerts
      description: This endpoint enables the retrieval of all alerts for a subscription.
      operationId: getSubscriptionAlerts
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      responses:
        '200':
          description: Subscription alerts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alerts'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
        - subscriptions
      summary: Create subscription alert(s)
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      description: This endpoint allows you to create alerts for a subscription. Send a single alert object wrapped in `alert` key to create one alert, or an array of alert objects wrapped in `alerts` key to create multiple alerts atomically.
      operationId: createSubscriptionAlert
      requestBody:
        description: Create one or more alerts for a subscription
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/AlertCreateInput'
                - $ref: '#/components/schemas/AlertBatchCreateInput'
        required: true
      responses:
        '200':
          description: Subscription alert(s) created
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Alert'
                  - $ref: '#/components/schemas/Alerts'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
        - subscriptions
      summary: Delete all subscription alerts
      description: This endpoint allows you to delete all alerts for a subscription.
      operationId: deleteAllSubscriptionAlerts
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      responses:
        '200':
          description: All subscription alerts deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /subscriptions/{external_id}/alerts/{code}:
    parameters:
      - name: external_id
        in: path
        description: External ID of the existing subscription
        required: true
        schema:
          type: string
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
      - name: code
        in: path
        description: Unique code of the alert
        required: true
        schema:
          type: string
          example: storage_threshold_alert
    get:
      tags:
        - subscriptions
      summary: Retrieve a subscription alert
      description: This endpoint enables the retrieval of a specific alert for a subscription.
      operationId: getSubscriptionAlert
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      responses:
        '200':
          description: Subscription alert
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
        - subscriptions
      summary: Update a subscription alert
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      description: This endpoint allows you to update an existing alert for a subscription.
      operationId: updateSubscriptionAlert
      requestBody:
        description: Update an existing alert for a subscription
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertUpdateInput'
        required: true
      responses:
        '200':
          description: Subscription alert updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
        - subscriptions
      summary: Delete a subscription alert
      description: This endpoint allows you to delete an existing alert for a subscription.
      operationId: deleteSubscriptionAlert
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      responses:
        '200':
          description: Subscription alert deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /subscriptions/{external_id}/entitlements:
    parameters:
      - name: external_id
        in: path
        description: External ID of the existing subscription
        required: true
        schema:
          type: string
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
    get:
      tags:
        - entitlements
      summary: List all subscription entitlements
      description: This endpoint retrieves all entitlements for a specific subscription, including both plan entitlements and any subscription-specific overrides.
      operationId: findAllSubscriptionEntitlements
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      responses:
        '200':
          description: List of subscription entitlements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEntitlements'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
        - entitlements
      summary: Update subscription entitlements
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      description: This accepts a list of entitlements to update. If the feature isn't part of the subscription yet, it's added with all the privileges from the payload. If the feature is already part of the subscription (via plan or via override), the privilege and values are updated or added. All privileges must be valid for the feature. All features  and privileges not part of the payload are left untouched. To remove privileges or features, use the DELETE endpoints.
      operationId: updateSubscriptionEntitlements
      requestBody:
        description: Subscription entitlements payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementUpdateInput'
        required: true
      responses:
        '200':
          description: Subscription entitlements updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEntitlements'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /subscriptions/{external_id}/entitlements/{feature_code}:
    parameters:
      - name: external_id
        in: path
        description: External ID of the existing subscription
        required: true
        schema:
          type: string
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
      - name: feature_code
        in: path
        description: Code of the existing feature
        required: true
        schema:
          type: string
          example: seats
    delete:
      tags:
        - entitlements
      summary: Remove an entitlement from a subscription
      description: This endpoint removes a specific feature entitlement from a subscription. The entitlement remains available from the plan.
      operationId: destroySubscriptionEntitlement
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      responses:
        '200':
          description: Subscription entitlement removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEntitlement'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /subscriptions/{external_id}/entitlements/{feature_code}/privileges/{privilege_code}:
    parameters:
      - name: external_id
        in: path
        description: External ID of the existing subscription
        required: true
        schema:
          type: string
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
      - name: feature_code
        in: path
        description: Code of the existing feature.
        required: true
        schema:
          type: string
          example: seats
      - name: privilege_code
        in: path
        description: Code of the privilege to remove from the subscription entitlement override.
        required: true
        schema:
          type: string
          example: max_admins
    delete:
      tags:
        - entitlements
      summary: Remove a privilege from a subscription entitlement override
      description: This endpoint removes a specific privilege from a subscription entitlement. The privilege entitlement remains available from the plan.
      operationId: destroySubscriptionEntitlementPrivilege
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      responses:
        '200':
          description: Subscription entitlement with privilege override removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEntitlement'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /subscriptions/{external_id}/fixed_charges:
    parameters:
      - $ref: '#/components/parameters/subscription_external_id_path'
    get:
      tags:
        - subscriptions
      summary: List all fixed charges for a subscription
      description: |-
        This endpoint retrieves all effective fixed charges for a specific subscription.
        The `units` of each fixed charge reflect any per-subscription unit override applied to the subscription; when no override exists, the plan-level units are returned.
      operationId: findAllSubscriptionFixedCharges
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - $ref: '#/components/parameters/subscription_status'
      responses:
        '200':
          description: List of fixed charges
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FixedChargesPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /subscriptions/{external_id}/charges:
    parameters:
      - $ref: '#/components/parameters/subscription_external_id_path'
    get:
      tags:
        - subscriptions
      summary: List all charges for a subscription
      description: |-
        This endpoint retrieves all effective charges for a specific subscription.
        If the subscription has plan overrides with charge overrides, the overridden charges are returned.
      operationId: findAllSubscriptionCharges
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - $ref: '#/components/parameters/subscription_status'
      responses:
        '200':
          description: List of charges
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargesPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /subscriptions/{external_id}/charges/{charge_code}:
    parameters:
      - $ref: '#/components/parameters/subscription_external_id_path'
      - $ref: '#/components/parameters/charge_code'
    get:
      tags:
        - subscriptions
      summary: Retrieve a charge for a subscription
      description: |-
        This endpoint retrieves a specific effective charge for a subscription.
        If the subscription has a plan override with a charge override, the overridden charge is returned.
      operationId: findSubscriptionCharge
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      responses:
        '200':
          description: Charge
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Charge'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
        - subscriptions
      summary: Override a charge for a subscription
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      description: |-
        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.
      operationId: overrideSubscriptionCharge
      requestBody:
        description: Charge override payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionChargeOverride'
        required: true
      responses:
        '200':
          description: Charge override created or updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Charge'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /subscriptions/{external_id}/charges/{charge_code}/filters:
    parameters:
      - $ref: '#/components/parameters/subscription_external_id_path'
      - $ref: '#/components/parameters/charge_code'
    post:
      tags:
        - subscriptions
      summary: Create a charge filter
      description: This endpoint creates a new filter for a specific charge on a subscription.
      operationId: createSubscriptionChargeFilter
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      requestBody:
        description: Charge filter payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeFilterCreateInput'
        required: true
      responses:
        '200':
          description: Charge filter created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeFilterResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - subscriptions
      summary: List all filters for a charge
      description: This endpoint retrieves all filters for a specific charge on a subscription.
      operationId: findAllSubscriptionChargeFilters
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - $ref: '#/components/parameters/subscription_status'
      responses:
        '200':
          description: List of charge filters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeFiltersPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /subscriptions/{external_id}/charges/{charge_code}/filters/{filter_id}:
    parameters:
      - $ref: '#/components/parameters/subscription_external_id_path'
      - $ref: '#/components/parameters/charge_code'
      - $ref: '#/components/parameters/charge_filter_id'
    get:
      tags:
        - subscriptions
      summary: Retrieve a charge filter
      description: This endpoint retrieves a specific filter for a charge on a subscription.
      operationId: findSubscriptionChargeFilter
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      responses:
        '200':
          description: Charge filter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeFilterResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
        - subscriptions
      summary: Update a charge filter
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      description: This endpoint updates a specific filter for a charge on a subscription.
      operationId: updateSubscriptionChargeFilter
      requestBody:
        description: Charge filter payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeFilterUpdateInput'
        required: true
      responses:
        '200':
          description: Charge filter updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeFilterResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
        - subscriptions
      summary: Delete a charge filter
      description: This endpoint deletes a specific filter from a charge on a subscription.
      operationId: destroySubscriptionChargeFilter
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      responses:
        '200':
          description: Charge filter deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeFilterResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /subscriptions/{external_id}/fixed_charges/{fixed_charge_code}:
    parameters:
      - $ref: '#/components/parameters/subscription_external_id_path'
      - $ref: '#/components/parameters/fixed_charge_code'
    get:
      tags:
        - subscriptions
      summary: Retrieve a fixed charge for a subscription
      description: |-
        This endpoint retrieves a specific effective fixed charge for a subscription.
        The `units` reflect any per-subscription unit override applied to the subscription; when no override exists, the plan-level units are returned.
      operationId: findSubscriptionFixedCharge
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      responses:
        '200':
          description: Fixed Charge
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FixedCharge'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
        - subscriptions
      summary: Override a fixed charge for a subscription
      parameters:
        - $ref: '#/components/parameters/subscription_status'
      description: |-
        This endpoint creates or updates a fixed charge override for a subscription, without affecting the original plan fixed charge.
        When the body contains only `units` (and optionally `apply_units_immediately`), the change is recorded as a per-subscription unit override. When the body also sets `invoice_display_name`, `properties`, or `tax_codes`, it is applied as a full plan override for the subscription instead.
        With `apply_units_immediately: true` on a pay-in-advance fixed charge the change is billed mid-period; otherwise it takes effect at the next billing period.
        This is a premium feature.
      operationId: overrideSubscriptionFixedCharge
      requestBody:
        description: Fixed charge override payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionFixedChargeOverride'
        required: true
      responses:
        '200':
          description: Fixed charge override created or updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FixedCharge'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /taxes:
    post:
      tags:
        - taxes
      summary: Create a tax
      description: This endpoint creates a new tax representing a customizable tax rate applicable to either the organization or a specific customer.
      operationId: createTax
      requestBody:
        description: Tax creation payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxCreateInput'
        required: true
      responses:
        '200':
          description: Tax created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tax'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - taxes
      summary: List all taxes
      description: This endpoint retrieves all existing taxes representing a customizable tax rate applicable to either the organization or a specific customer.
      operationId: findAllTaxes
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: Taxes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxesPaginated'
              example:
                taxes:
                  - lago_id: 41190609-391a-4368-9549-d4348a85a8cd
                    name: TVA
                    code: french_standard_vat
                    description: French standard VAT
                    rate: 20
                    applied_to_organization: true
                    created_at: '2023-07-06T14:35:58Z'
                  - lago_id: 2e034a10-6652-4daf-a600-b085184f93ad
                    name: TVA
                    code: french_reduced_vat
                    description: French reduce VAT
                    rate: 5
                    applied_to_organization: false
                    created_at: '2023-07-06T14:45:23Z'
                meta:
                  current_page: 1
                  next_page: null
                  prev_page: null
                  total_pages: 1
                  total_count: 2
        '401':
          $ref: '#/components/responses/Unauthorized'
  /taxes/{code}:
    parameters:
      - name: code
        in: path
        description: The code of the tax. It serves as a unique identifier associated with a particular tax. The code is typically used for internal or system-level identification purposes.
        required: true
        schema:
          type: string
          example: french_standard_vat
    put:
      tags:
        - taxes
      summary: Update a tax
      description: This endpoint updates an existing tax representing a customizable tax rate applicable to either the organization or a specific customer.
      operationId: updateTax
      requestBody:
        description: Tax update payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxUpdateInput'
        required: true
      responses:
        '200':
          description: Tax updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tax'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - taxes
      summary: Retrieve a Tax
      description: This endpoint retrieves an existing tax representing a customizable tax rate applicable to either the organization or a specific customer. The tax is identified by its unique code.
      operationId: findTax
      responses:
        '200':
          description: Tax
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tax'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - taxes
      summary: Delete a tax
      description: This endpoint is used to delete a tax.
      operationId: destroyTax
      responses:
        '200':
          description: Tax deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tax'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /wallets:
    post:
      tags:
        - wallets
      summary: Create a wallet
      description: This endpoint is used to create a wallet with prepaid credits.
      operationId: createWallet
      requestBody:
        description: Wallet payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletCreateInput'
        required: true
      responses:
        '200':
          description: Wallet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Wallet'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - wallets
      summary: List all wallets
      description: This endpoint is used to list all wallets with prepaid credits.
      operationId: findAllWallets
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - $ref: '#/components/parameters/currency'
        - name: external_customer_id
          in: query
          description: The customer external unique identifier (provided by your own application).
          required: true
          explode: true
          schema:
            type: string
            example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        - name: billing_entity_codes[]
          in: query
          description: Filter wallets by billing entity codes.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
            example:
              - billing_entity_code_1
              - billing_entity_code_2
      responses:
        '200':
          description: Wallets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /wallets/{lago_id}:
    parameters:
      - name: lago_id
        in: path
        description: Unique identifier assigned to the wallet within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the wallet's record within the Lago system.
        required: true
        schema:
          type: string
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
    put:
      tags:
        - wallets
      summary: Update a wallet
      description: This endpoint is used to update an existing wallet with prepaid credits.
      operationId: updateWallet
      requestBody:
        description: Wallet update payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletUpdateInput'
        required: true
      responses:
        '200':
          description: Wallet updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Wallet'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - wallets
      summary: Retrieve a wallet
      description: This endpoint is used to retrieve an existing wallet with prepaid credits.
      operationId: findWallet
      responses:
        '200':
          description: Wallet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Wallet'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - wallets
      summary: Terminate a wallet
      description: This endpoint is used to terminate an existing wallet with prepaid credits.
      operationId: destroyWallet
      responses:
        '200':
          description: Wallet terminated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Wallet'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /wallets/{lago_id}/metadata:
    post:
      tags:
        - wallets
      summary: Replace wallet metadata
      description: |-
        This endpoint replaces all existing metadata on a wallet with the provided key-value pairs.
        Any existing metadata keys not included in the request will be removed.
      parameters:
        - name: lago_id
          in: path
          description: Unique identifier assigned to the wallet within the Lago application.
          required: true
          schema:
            type: string
            format: uuid
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
      operationId: replaceWalletMetadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletMetadataResponse'
      responses:
        '200':
          description: Wallet metadata replaced
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletMetadataResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    patch:
      tags:
        - wallets
      summary: Merge wallet metadata
      description: |-
        This endpoint merges the provided metadata with existing metadata on the wallet.
        Existing keys not in the request are preserved. New keys are added, existing keys are updated.
      parameters:
        - name: lago_id
          in: path
          description: Unique identifier assigned to the wallet within the Lago application.
          required: true
          schema:
            type: string
            format: uuid
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
      operationId: mergeWalletMetadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletMetadataResponse'
      responses:
        '200':
          description: Wallet metadata merged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletMetadataResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
        - wallets
      summary: Delete all wallet metadata
      description: This endpoint removes all metadata from a wallet.
      parameters:
        - name: lago_id
          in: path
          description: Unique identifier assigned to the wallet within the Lago application.
          required: true
          schema:
            type: string
            format: uuid
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
      operationId: deleteAllWalletMetadata
      responses:
        '200':
          description: Wallet metadata deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletMetadataResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /wallets/{lago_id}/metadata/{key}:
    delete:
      tags:
        - wallets
      summary: Delete a metadata key
      description: This endpoint removes a single metadata key from a wallet.
      parameters:
        - name: lago_id
          in: path
          description: Unique identifier assigned to the wallet within the Lago application.
          required: true
          schema:
            type: string
            format: uuid
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        - name: key
          in: path
          description: The metadata key to delete.
          required: true
          schema:
            type: string
            example: external_id
      operationId: deleteWalletMetadataKey
      responses:
        '200':
          description: Metadata key deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletMetadataResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /wallet_transactions:
    post:
      tags:
        - wallets
      summary: Top up a wallet
      description: This endpoint is used to top-up an active wallet.
      operationId: createWalletTransaction
      requestBody:
        description: Wallet transaction payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletTransactionCreateInput'
        required: true
      responses:
        '200':
          description: Wallet transaction created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletTransactions'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /wallet_transactions/{lago_id}:
    parameters:
      - name: lago_id
        in: path
        description: Unique identifier assigned to the wallet transaction within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the wallet's record within the Lago system.
        required: true
        schema:
          type: string
          format: uuid
          example: bb0a27be-51f7-4f4f-aad0-2abc80534c0f
    get:
      tags:
        - wallets
      summary: Retrieve a wallet transaction
      description: This endpoint is used to retrieve a specific wallet transactions.
      operationId: findWalletTransaction
      responses:
        '200':
          description: Wallet transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletTransactionObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /wallet_transactions/{lago_id}/payment_url:
    post:
      tags:
        - wallets
      summary: Generate a payment URL
      description: This endpoint generates a checkout link for a specific wallet transaction.
      parameters:
        - name: lago_id
          in: path
          description: ID of the wallet transaction.
          required: true
          schema:
            type: string
            format: uuid
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
      operationId: walletTransactionPaymentUrl
      responses:
        '200':
          description: Payment URL has been generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletTransactionPaymentUrl'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /wallet_transactions/{lago_id}/consumptions:
    get:
      tags:
        - wallets
      summary: List all consumptions for a wallet transaction
      description: This endpoint is used to list all consumption records for an inbound wallet transaction. It shows how the credits from this inbound transaction were consumed by outbound transactions. Only available for traceable wallets.
      operationId: findAllWalletTransactionConsumptions
      parameters:
        - name: lago_id
          in: path
          description: Unique identifier assigned to the wallet transaction within the Lago application. Must be an inbound wallet transaction.
          required: true
          schema:
            type: string
            format: uuid
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: Wallet transaction consumptions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletTransactionConsumptionsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /wallet_transactions/{lago_id}/fundings:
    get:
      tags:
        - wallets
      summary: List all fundings for a wallet transaction
      description: This endpoint is used to list all funding records for an outbound wallet transaction. It shows which inbound transactions funded this outbound transaction. Only available for traceable wallets.
      operationId: findAllWalletTransactionFundings
      parameters:
        - name: lago_id
          in: path
          description: Unique identifier assigned to the wallet transaction within the Lago application. Must be an outbound wallet transaction.
          required: true
          schema:
            type: string
            format: uuid
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: Wallet transaction fundings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletTransactionFundingsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /wallets/{lago_id}/wallet_transactions:
    get:
      tags:
        - wallets
      summary: List all wallet transactions
      description: This endpoint is used to list all wallet transactions.
      operationId: findAllWalletTransactions
      parameters:
        - name: lago_id
          in: path
          description: Unique identifier assigned to the wallet within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the wallet's record within the Lago system.
          required: true
          schema:
            type: string
            format: uuid
            example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - name: status
          in: query
          description: The status of the wallet transaction. Possible values are `pending` or `settled`.
          required: false
          explode: true
          schema:
            type: string
            example: pending
        - name: transaction_status
          in: query
          description: The transaction status of the wallet transaction. Possible values are `purchased` (with pending or settled status), `granted` (without invoice_id), `voided` or `invoiced`.
          required: false
          explode: true
          schema:
            type: string
            example: purchased
        - name: transaction_type
          in: query
          description: The transaction type of the wallet transaction. Possible values are `inbound` (increasing the wallet balance) or `outbound` (decreasing the wallet balance).
          required: false
          explode: true
          schema:
            type: string
            example: inbound
      responses:
        '200':
          description: Wallet transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletTransactionsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /webhooks/public_key:
    get:
      tags:
        - webhooks
      summary: Retrieve webhook public key
      description: This endpoint is used to retrieve the public key used to verify the webhooks signature
      deprecated: true
      operationId: fetchPublicKey
      responses:
        '200':
          description: Public key
          content:
            text/plain:
              schema:
                type: string
                example: MEgCQQCo9+BpMRYQ/dL3DS2CyJxRF+j6ctbT3/Qp84+KeFhnii7NT7fELilKUSnxS30WAvQCCo2yU1orfgqr41mM70MBAgMBAAE=
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhooks/json_public_key:
    get:
      tags:
        - webhooks
      summary: Retrieve webhook public key (JSON)
      description: This endpoint is used to retrieve the public key used to verify the webhooks signature, wrapped in a JSON object. Prefer this endpoint over the deprecated GET /webhooks/public_key.
      operationId: fetchJsonPublicKey
      responses:
        '200':
          description: Public key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookPublicKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhook_endpoints:
    post:
      tags:
        - webhook_endpoints
      summary: Create a webhook_endpoint
      description: This endpoint is used to create a webhook endpoint.
      operationId: createWebhookEndpoint
      requestBody:
        description: Webhook Endpoint payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointCreateInput'
        required: true
      responses:
        '200':
          description: Webhook Endpoint created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - webhook_endpoints
      summary: List all webhook endpoints
      description: This endpoint is used to list all webhook endpoints.
      operationId: findAllWebhookEndpoints
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: WebhookEndpoints
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhook_endpoints/{lago_id}:
    parameters:
      - name: lago_id
        in: path
        description: Unique identifier assigned to the webhook endpoint within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the webhook endpoint's record within the Lago system.
        required: true
        schema:
          type: string
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
    put:
      tags:
        - webhook_endpoints
      summary: Update a webhook endpoint
      description: This endpoint is used to update an existing webhook endpoint.
      operationId: updateWebhookEndpoint
      requestBody:
        description: Webhook Endpoint update payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointUpdateInput'
        required: true
      responses:
        '200':
          description: Webhook Endpoint updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
        - webhook_endpoints
      summary: Retrieve a webhook endpoint
      description: This endpoint is used to retrieve an existing webhook endpoint.
      operationId: findWebhookEndpoint
      responses:
        '200':
          description: WebhookEndpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - webhook_endpoints
      summary: Delete a webhook endpoint
      description: This endpoint is used to delete an existing webhook endpoint.
      operationId: destroyWebhookEndpoint
      responses:
        '200':
          description: Webhook Endpoint deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/NotAllowed'
webhooks:
  alert_triggered:
    post:
      operationId: alertTriggered
      summary: A new alert was triggered
      description: One or more thresholds defined in the alert were crossed
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the triggered alert
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - triggered_alert
              properties:
                webhook_type:
                  type: string
                  enum:
                    - alert.triggered
                object_type:
                  type: string
                  enum:
                    - triggered_alert
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                triggered_alert:
                  $ref: '#/components/schemas/TriggeredAlertObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  billable_metric_created:
    post:
      operationId: billableMetricCreated
      summary: A new billable metric has been created
      description: A new billable metric has been created
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the new billable metric
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - billable_metric
              properties:
                webhook_type:
                  type: string
                  enum:
                    - billable_metric.created
                object_type:
                  type: string
                  enum:
                    - billable_metric
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                billable_metric:
                  $ref: '#/components/schemas/BillableMetricObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  billable_metric_updated:
    post:
      operationId: billableMetricUpdated
      summary: A billable metric has been updated
      description: A billable metric has been updated
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the billable metric
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - billable_metric
              properties:
                webhook_type:
                  type: string
                  enum:
                    - billable_metric.updated
                object_type:
                  type: string
                  enum:
                    - billable_metric
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                billable_metric:
                  $ref: '#/components/schemas/BillableMetricObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  billable_metric_deleted:
    post:
      operationId: billableMetricDeleted
      summary: A billable metric has been deleted
      description: A billable metric has been deleted
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the billable metric
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - billable_metric
              properties:
                webhook_type:
                  type: string
                  enum:
                    - billable_metric.deleted
                object_type:
                  type: string
                  enum:
                    - billable_metric
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                billable_metric:
                  $ref: '#/components/schemas/BillableMetricObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  customer_created:
    post:
      operationId: customerCreated
      summary: A new customer has been created
      description: A new customer has been created
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the new customer
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - customer
              properties:
                webhook_type:
                  type: string
                  enum:
                    - customer.created
                object_type:
                  type: string
                  enum:
                    - customer
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                customer:
                  $ref: '#/components/schemas/CustomerObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  customer_updated:
    post:
      operationId: customerUpdated
      summary: A customer has been updated
      description: A customer has been updated
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the customer
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - customer
              properties:
                webhook_type:
                  type: string
                  enum:
                    - customer.updated
                object_type:
                  type: string
                  enum:
                    - customer
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                customer:
                  $ref: '#/components/schemas/CustomerObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  customer_accounting_provider_created:
    post:
      operationId: customerAccountingProviderCreated
      summary: A customer was created on an accouting integration
      description: A customer was created on an accouting integration
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the customer
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - customer
              properties:
                webhook_type:
                  type: string
                  enum:
                    - customer.accounting_provider_created
                object_type:
                  type: string
                  enum:
                    - customer
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                customer:
                  $ref: '#/components/schemas/CustomerObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  customer_accounting_provider_error:
    post:
      operationId: customerAccountingProviderError
      summary: An error was encountered while syncing a customer to an accounting provider
      description: An error was encountered while syncing a customer to an accounting provider
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the customer and of the provider error
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - accounting_provider_customer_error
              properties:
                webhook_type:
                  type: string
                  enum:
                    - customer.accounting_provider_error
                object_type:
                  type: string
                  enum:
                    - accounting_provider_customer_error
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                accounting_provider_customer_error:
                  $ref: '#/components/schemas/CustomerIntegratrionErrorObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  customer_crm_provider_created:
    post:
      operationId: customerCrmProviderCreated
      summary: A customer has been created in the CRM provider
      description: A customer has been created in the CRM provider
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the customer
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - customer
              properties:
                webhook_type:
                  type: string
                  enum:
                    - customer.crm_provider_created
                object_type:
                  type: string
                  enum:
                    - customer
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                customer:
                  $ref: '#/components/schemas/CustomerObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  customer_crm_provider_error:
    post:
      operationId: customerCrmProviderError
      summary: An error was encountered while syncing a customer to a CRM provider
      description: An error was encountered while syncing a customer to a CRM provider
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the customer and of the CRM provider error
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - crm_provider_customer_error
              properties:
                webhook_type:
                  type: string
                  enum:
                    - customer.crm_provider_error
                object_type:
                  type: string
                  enum:
                    - crm_provider_customer_error
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                crm_provider_customer_error:
                  $ref: '#/components/schemas/CustomerIntegratrionErrorObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  customer_payment_provider_created:
    post:
      operationId: customerPaymentProviderCreated
      summary: A customer has been created on a payment provider
      description: A customer has been created on a payment provider
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the customer
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - customer
              properties:
                webhook_type:
                  type: string
                  enum:
                    - customer.payment_provider_created
                object_type:
                  type: string
                  enum:
                    - customer
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                customer:
                  $ref: '#/components/schemas/CustomerObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  customer_payment_provider_error:
    post:
      operationId: customerPaymentProviderError
      summary: An error was encountered while syncing a customer to a payment provider
      description: An error was encountered while syncing a customer to a payment provider
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the customer and of the payment provider error
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - payment_provider_customer_error
              properties:
                webhook_type:
                  type: string
                  enum:
                    - customer.payment_provider_error
                object_type:
                  type: string
                  enum:
                    - payment_provider_customer_error
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                payment_provider_customer_error:
                  $ref: '#/components/schemas/CustomerPaymentProviderErrorObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  customer_checkout_url_generated:
    post:
      operationId: customerCheckoutUrlGenerated
      summary: A checkout URL was generated for a customer
      description: A checkout URL was generated for a customer
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the customer with the generated checkout URL
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - payment_provider_customer_checkout_url
              properties:
                webhook_type:
                  type: string
                  enum:
                    - customer.checkout_url_generated
                object_type:
                  type: string
                  enum:
                    - payment_provider_customer_checkout_url
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                payment_provider_customer_checkout_url:
                  $ref: '#/components/schemas/CustomerCheckoutUrl'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  customer_tax_provider_error:
    post:
      operationId: customerTaxProviderError
      summary: An error was encountered while fetching taxes for a customer on a tax provider
      description: An error was encountered while fetching taxes for a customer on a tax provider
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the customer and of the tax provider error
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - tax_provider_customer_error
              properties:
                webhook_type:
                  type: string
                  enum:
                    - customer.tax_provider_error
                object_type:
                  type: string
                  enum:
                    - tax_provider_customer_error
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                tax_provider_customer_error:
                  $ref: '#/components/schemas/CustomerTaxProviderErrorObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  customer_vies_check:
    post:
      operationId: customerViesCheck
      summary: VIES VAT number has been checked for a customer
      description: VIES VAT number has been checked for a customer
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the customer with the VIES VAT check status
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - customer
              properties:
                webhook_type:
                  type: string
                  enum:
                    - customer.vies_check
                object_type:
                  type: string
                  enum:
                    - customer
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                customer:
                  $ref: '#/components/schemas/CustomerViesCheckObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  credit_note_created:
    post:
      operationId: creditNoteCreated
      summary: A new credit note has been created
      description: A new credit note has been created
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the new credit note
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - credit_note
              properties:
                webhook_type:
                  type: string
                  enum:
                    - credit_note.created
                object_type:
                  type: string
                  enum:
                    - credit_note
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                credit_note:
                  $ref: '#/components/schemas/CreditNoteExtendedObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  credit_note_generated:
    post:
      operationId: creditNoteGenerated
      summary: A new credit note PDF has been generated
      description: A new credit note PDF has been generated
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the credit note
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - credit_note
              properties:
                webhook_type:
                  type: string
                  enum:
                    - credit_note.generated
                object_type:
                  type: string
                  enum:
                    - credit_note
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                credit_note:
                  $ref: '#/components/schemas/CreditNoteExtendedObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  credit_note_provider_refund_failure:
    post:
      operationId: creditNoteProviderRefundFailure
      summary: The refund of a credit note has failed on a payment provider
      description: The refund of a credit note has failed on a payment provider
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the credit note and of the provider error
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - credit_note_payment_provider_refund_error
              properties:
                webhook_type:
                  type: string
                  enum:
                    - credit_note.refund_failure
                object_type:
                  type: string
                  enum:
                    - credit_note_payment_provider_refund_error
                credit_note_payment_provider_refund_error:
                  $ref: '#/components/schemas/CreditNotePaymentProviderRefundError'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  dunning_campaign_finished:
    post:
      operationId: dunningCampaignFinished
      summary: The dunning campaign has been completed for a customer
      description: The dunning campaign has been completed for a customer
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the finished dunning campaign and the overdue balance
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - dunning_campaign
              properties:
                webhook_type:
                  type: string
                  enum:
                    - dunning_campaign.finished
                object_type:
                  type: string
                  enum:
                    - dunning_campaign
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                dunning_campaign:
                  $ref: '#/components/schemas/DunningCampaignFinishedObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  event_error:
    post:
      deprecated: true
      operationId: eventError
      summary: An error has been detected on an event
      description: An error has been detected on an event
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the event and of the error
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - event_error
              properties:
                webhook_type:
                  type: string
                  enum:
                    - event.error
                object_type:
                  type: string
                  enum:
                    - event_error
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                event_error:
                  $ref: '#/components/schemas/EventErrorsObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  events_errors:
    post:
      operationId: eventsErrors
      summary: Errors were encountered while post-processing some events
      description: Errors were encountered while post-processing some events
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the events errors
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - events_errors
              properties:
                webhook_type:
                  type: string
                  enum:
                    - events.errors
                object_type:
                  type: string
                  enum:
                    - events_errors
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                events_errors:
                  $ref: '#/components/schemas/EventsErrorsObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  feature.created:
    post:
      operationId: featureCreated
      summary: A new feature has been created
      description: A new feature has been created
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the new feature
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - feature
              properties:
                webhook_type:
                  type: string
                  enum:
                    - feature.created
                object_type:
                  type: string
                  enum:
                    - feature
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                feature:
                  $ref: '#/components/schemas/FeatureObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  feature.updated:
    post:
      operationId: featureUpdated
      summary: A feature has been updated
      description: A feature has been updated
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the feature
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - feature
              properties:
                webhook_type:
                  type: string
                  enum:
                    - feature.updated
                object_type:
                  type: string
                  enum:
                    - feature
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                feature:
                  $ref: '#/components/schemas/FeatureObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  feature.deleted:
    post:
      operationId: featureDeleted
      summary: A feature has been deleted
      description: A feature has been deleted
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the feature
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - feature
              properties:
                webhook_type:
                  type: string
                  enum:
                    - feature.deleted
                object_type:
                  type: string
                  enum:
                    - feature
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                feature:
                  $ref: '#/components/schemas/FeatureObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  fee_created:
    post:
      operationId: feeCreated
      summary: A pay in advance fee has been created
      description: A pay in advance fee has been created
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the new fee
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - fee
              properties:
                webhook_type:
                  type: string
                  enum:
                    - fee.created
                object_type:
                  type: string
                  enum:
                    - fee
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                fee:
                  $ref: '#/components/schemas/FeeObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  fee_tax_provider_error:
    post:
      operationId: feeTaxProviderError
      summary: An error was encountered while fetching taxes for a fee on a tax provider
      description: An error was encountered while fetching taxes for a fee on a tax provider
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the fee and of the tax provider error
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - tax_provider_fee_error
              properties:
                webhook_type:
                  type: string
                  enum:
                    - fee.tax_provider_error
                object_type:
                  type: string
                  enum:
                    - tax_provider_fee_error
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                tax_provider_fee_error:
                  $ref: '#/components/schemas/FeeTaxProviderErrorObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  invoice_created:
    post:
      operationId: invoiceCreated
      summary: A new invoice has been emitted
      description: A new invoice has been emitted
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the new invoice
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - invoice
              properties:
                webhook_type:
                  type: string
                  enum:
                    - invoice.created
                object_type:
                  type: string
                  enum:
                    - invoice
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                invoice:
                  $ref: '#/components/schemas/InvoiceObjectExtended'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  invoice_one_off_created:
    post:
      operationId: invoiceOneOffCreated
      summary: A new one off invoice has been emitted
      description: A new one off invoice has been emitted
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the new invoice
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - invoice
              properties:
                webhook_type:
                  type: string
                  enum:
                    - invoice.one_off_created
                object_type:
                  type: string
                  enum:
                    - invoice
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                invoice:
                  $ref: '#/components/schemas/InvoiceObjectExtended'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  invoice_add_on_added:
    post:
      operationId: invoiceAddOnAdded
      summary: A new add on invoice has been emitted
      description: A new add on invoice has been emitted
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the new invoice
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - invoice
              properties:
                webhook_type:
                  type: string
                  enum:
                    - invoice.add_on_added
                object_type:
                  type: string
                  enum:
                    - invoice
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                invoice:
                  $ref: '#/components/schemas/InvoiceObjectExtended'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  invoice_paid_credit_added:
    post:
      operationId: invoicePaidCreditAdded
      summary: A new prepaid credit invoice has been emitted
      description: A new prepaid credit invoice has been emitted
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the new invoice
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - invoice
              properties:
                webhook_type:
                  type: string
                  enum:
                    - invoice.paid_credit_added
                object_type:
                  type: string
                  enum:
                    - invoice
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                invoice:
                  $ref: '#/components/schemas/InvoiceObjectExtended'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  invoice_generated:
    post:
      operationId: invoiceGenerated
      summary: A new invoice PDF has been generated
      description: A new invoice PDF has been generated
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the invoice
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - invoice
              properties:
                webhook_type:
                  type: string
                  enum:
                    - invoice.generated
                object_type:
                  type: string
                  enum:
                    - invoice
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                invoice:
                  $ref: '#/components/schemas/InvoiceObjectExtended'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  invoice_drafted:
    post:
      operationId: invoiceDrafted
      summary: A new draft invoice has been emitted
      description: A new draft invoice has been emitted
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the new invoice
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - invoice
              properties:
                webhook_type:
                  type: string
                  enum:
                    - invoice.drafted
                object_type:
                  type: string
                  enum:
                    - invoice
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                invoice:
                  $ref: '#/components/schemas/InvoiceObjectExtended'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  invoice_voided:
    post:
      operationId: invoiceVoided
      summary: An invoice has been voided
      description: An invoice has been voided
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the invoice
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - invoice
              properties:
                webhook_type:
                  type: string
                  enum:
                    - invoice.voided
                object_type:
                  type: string
                  enum:
                    - invoice
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                invoice:
                  $ref: '#/components/schemas/InvoiceObjectExtended'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  invoice_deleted:
    post:
      operationId: invoiceDeleted
      summary: A draft invoice has been deleted
      description: A draft invoice has been deleted
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the invoice
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - invoice
              properties:
                webhook_type:
                  type: string
                  enum:
                    - invoice.deleted
                object_type:
                  type: string
                  enum:
                    - invoice
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                invoice:
                  $ref: '#/components/schemas/InvoiceObjectExtended'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  invoice_payment_dispute_lost:
    post:
      operationId: invoicePaymentDisputeLost
      summary: A payment dispute has been lost for an invoice payment
      description: A payment dispute has been lost for an invoice payment
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the invoice and of the payment dispute
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - payment_dispute_lost
              properties:
                webhook_type:
                  type: string
                  enum:
                    - invoice.payment_dispute_lost
                object_type:
                  type: string
                  enum:
                    - payment_dispute_lost
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                payment_dispute_lost:
                  $ref: '#/components/schemas/InvoicePaymentDisputeLostObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  invoice_payment_status_updated:
    post:
      operationId: invoicePaymentStatusUpdated
      summary: The payment status of an invoice has been updated
      description: The payment status of an invoice has been updated
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the invoice
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - invoice
              properties:
                webhook_type:
                  type: string
                  enum:
                    - invoice.payment_status_updated
                object_type:
                  type: string
                  enum:
                    - invoice
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                invoice:
                  $ref: '#/components/schemas/InvoiceObjectExtended'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  invoice_payment_overdue:
    post:
      operationId: invoicePaymentOverdue
      summary: An invoice payment is overdue
      description: An invoice payment is overdue
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the invoice
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - invoice
              properties:
                webhook_type:
                  type: string
                  enum:
                    - invoice.payment_overdue
                object_type:
                  type: string
                  enum:
                    - invoice
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                invoice:
                  $ref: '#/components/schemas/InvoiceObjectExtended'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  invoice_payment_failure:
    post:
      operationId: invoicePaymentFailure
      summary: A payment attempt for an invoice has failed on a payment provider
      description: A payment attempt for an invoice has failed on a payment provider
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the invoice and of the payment provider error
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - payment_provider_invoice_payment_error
              properties:
                webhook_type:
                  type: string
                  enum:
                    - invoice.payment_failure
                object_type:
                  type: string
                  enum:
                    - payment_provider_invoice_payment_error
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                payment_provider_invoice_payment_error:
                  $ref: '#/components/schemas/InvoicePaymentFailureObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  invoice_resynced:
    post:
      operationId: invoiceResynced
      summary: An invoice has been resynced with salesforce
      description: An invoice has been resynced with salesforce
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the invoice
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - invoice
              properties:
                webhook_type:
                  type: string
                  enum:
                    - invoice.resynced
                object_type:
                  type: string
                  enum:
                    - invoice
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                invoice:
                  $ref: '#/components/schemas/InvoiceObjectExtended'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  integration_provider_error:
    post:
      operationId: integrationProviderError
      summary: An error was encountered while processing data on an integration
      description: An error was encountered while processing data on an integration
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the integration and of the integration error
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - provider_error
              properties:
                webhook_type:
                  type: string
                  enum:
                    - integration.provider_error
                object_type:
                  type: string
                  enum:
                    - provider_error
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                provider_error:
                  $ref: '#/components/schemas/IntegrationProviderErrorObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  payment_requires_action:
    post:
      operationId: paymentRequiresAction
      summary: An action is required to process a payment
      description: An action is required to process a payment
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the payment and of the required action
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - payment
              properties:
                webhook_type:
                  type: string
                  enum:
                    - payment.requires_action
                object_type:
                  type: string
                  enum:
                    - payment
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                payment:
                  $ref: '#/components/schemas/PaymentObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  payment_succeeded:
    post:
      operationId: paymentSucceeded
      summary: A payment has been successfully processed
      description: A payment has been successfully processed by the payment provider
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the successfully processed payment
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - payment
              properties:
                webhook_type:
                  type: string
                  enum:
                    - payment.succeeded
                object_type:
                  type: string
                  enum:
                    - payment
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                payment:
                  $ref: '#/components/schemas/PaymentObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  payment_provider_error:
    post:
      operationId: paymentProviderError
      summary: An error was raised by a payment provider
      description: An error was raised by a payment provider
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the payment provider and of the error
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - payment_provider_error
              properties:
                webhook_type:
                  type: string
                  enum:
                    - payment_provider.error
                object_type:
                  type: string
                  enum:
                    - payment_provider_error
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                payment_provider_error:
                  $ref: '#/components/schemas/PaymentProviderErrorObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  payment_request_created:
    post:
      operationId: paymentRequestCreated
      summary: An new payment request has been created
      description: An new payment request has been created
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the new payment request
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - payment_request
              properties:
                webhook_type:
                  type: string
                  enum:
                    - payment_request.created
                object_type:
                  type: string
                  enum:
                    - payment_request
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                payment_request:
                  $ref: '#/components/schemas/PaymentRequestObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  payment_request_payment_failure:
    post:
      operationId: paymentRequestPaymentFailure
      summary: A payment attempt for a payment request has failed on a payment provider
      description: A payment attempt for a payment request has failed on a payment provider
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the payment request and of the provider error
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - payment_provider_payment_request_payment_error
              properties:
                webhook_type:
                  type: string
                  enum:
                    - payment_request.payment_failure
                object_type:
                  type: string
                  enum:
                    - payment_provider_payment_request_payment_error
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                payment_provider_payment_request_payment_error:
                  $ref: '#/components/schemas/PaymentRequestPaymentFailureObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  payment_request_payment_status_updated:
    post:
      operationId: paymentRequestPaymentStatusUpdated
      summary: The payment status of an invoice has been updated
      description: The payment status of an invoice has been updated
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the payment request
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - payment_request
              properties:
                webhook_type:
                  type: string
                  enum:
                    - payment_request.payment_status_updated
                object_type:
                  type: string
                  enum:
                    - payment_request
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                payment_request:
                  $ref: '#/components/schemas/PaymentRequestObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  plan_created:
    post:
      operationId: planCreated
      summary: A new plan has been created
      description: A new plan has been created
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the new plan
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - plan
              properties:
                webhook_type:
                  type: string
                  enum:
                    - plan.created
                object_type:
                  type: string
                  enum:
                    - plan
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                plan:
                  $ref: '#/components/schemas/PlanObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  plan_updated:
    post:
      operationId: planUpdated
      summary: A plan has been updated
      description: A plan has been updated
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the plan
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - plan
              properties:
                webhook_type:
                  type: string
                  enum:
                    - plan.updated
                object_type:
                  type: string
                  enum:
                    - plan
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                plan:
                  $ref: '#/components/schemas/PlanObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  plan_deleted:
    post:
      operationId: planDeleted
      summary: A plan has been deleted
      description: A plan has been deleted
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the plan
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - plan
              properties:
                webhook_type:
                  type: string
                  enum:
                    - plan.deleted
                object_type:
                  type: string
                  enum:
                    - plan
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                plan:
                  $ref: '#/components/schemas/PlanObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  subscription_terminated:
    post:
      operationId: subscriptionTerminated
      summary: A subscription has been terminated
      description: A subscription has been terminated
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the subscription
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - subscription
              properties:
                webhook_type:
                  type: string
                  enum:
                    - subscription.terminated
                object_type:
                  type: string
                  enum:
                    - subscription
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                subscription:
                  $ref: '#/components/schemas/SubscriptionWithCustomerObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  subscription_incomplete:
    post:
      operationId: subscriptionIncomplete
      summary: A subscription is incomplete and waiting for payment
      description: A payment-gated subscription has been created in the `incomplete` state and is waiting for the gating payment to succeed before it is activated.
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the subscription
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - subscription
              properties:
                webhook_type:
                  type: string
                  enum:
                    - subscription.incomplete
                object_type:
                  type: string
                  enum:
                    - subscription
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                subscription:
                  $ref: '#/components/schemas/SubscriptionWithCustomerObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  subscription_canceled:
    post:
      operationId: subscriptionCanceled
      summary: A subscription has been canceled
      description: A subscription has been canceled before its activation. For payment-gated subscriptions this happens when the gating payment fails or the activation rule expires, in which case the `cancellation_reason` field is set.
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the subscription
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - subscription
              properties:
                webhook_type:
                  type: string
                  enum:
                    - subscription.canceled
                object_type:
                  type: string
                  enum:
                    - subscription
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                subscription:
                  $ref: '#/components/schemas/SubscriptionWithCustomerObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  subscription_started:
    post:
      operationId: subscriptionStarted
      summary: An subscription has started
      description: An subscription has started
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the subscription
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - subscription
              properties:
                webhook_type:
                  type: string
                  enum:
                    - subscription.started
                object_type:
                  type: string
                  enum:
                    - subscription
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                subscription:
                  $ref: '#/components/schemas/SubscriptionWithCustomerObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  subscription_updated:
    post:
      operationId: subscriptionUpdated
      summary: A subscription has been updated
      description: A subscription has been updated
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the subscription
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - subscription
              properties:
                webhook_type:
                  type: string
                  enum:
                    - subscription.updated
                object_type:
                  type: string
                  enum:
                    - subscription
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                subscription:
                  $ref: '#/components/schemas/SubscriptionWithCustomerObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  subscription_termination_alert:
    post:
      operationId: subscriptionTerminationAlert
      summary: A subscription will be terminated in the future
      description: A subscription will be terminated in the future
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the subscription
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - subscription
              properties:
                webhook_type:
                  type: string
                  enum:
                    - subscription.termination_alert
                object_type:
                  type: string
                  enum:
                    - subscription
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                subscription:
                  $ref: '#/components/schemas/SubscriptionWithCustomerObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  subscription_trial_ended:
    post:
      operationId: subscriptionTrialEnded
      summary: A subscription trial period has ended
      description: A subscription trial period has ended
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the subscription
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - subscription
              properties:
                webhook_type:
                  type: string
                  enum:
                    - subscription.trial_ended
                object_type:
                  type: string
                  enum:
                    - subscription
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                subscription:
                  $ref: '#/components/schemas/SubscriptionWithCustomerObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  subscription_usage_threshold_reached:
    post:
      operationId: subscriptionUsageThresholdReached
      summary: A usage threshold has been reached by a subscription
      description: A usage threshold has been reached by a subscription
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the subscription and of the reached threshold
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - subscription
              properties:
                webhook_type:
                  type: string
                  enum:
                    - subscription.usage_threshold_reached
                object_type:
                  type: string
                  enum:
                    - subscription
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                subscription:
                  $ref: '#/components/schemas/SubscriptionWithThresholdObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  wallet_depleted_ongoing_balance:
    post:
      operationId: walletDepletedOngoingBalance
      summary: The balance of a wallet has been depleted
      description: The balance of a wallet has been depleted
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the wallet
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - wallet
              properties:
                webhook_type:
                  type: string
                  enum:
                    - wallet.depleted_ongoing_balance
                object_type:
                  type: string
                  enum:
                    - wallet
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                wallet:
                  $ref: '#/components/schemas/WalletObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  wallet_transaction_created:
    post:
      operationId: walletTransactionCreated
      summary: A new wallet transaction has been created
      description: A new wallet transaction has been created
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the wallet transaction
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - wallet_transaction
              properties:
                webhook_type:
                  type: string
                  enum:
                    - wallet_transaction.created
                object_type:
                  type: string
                  enum:
                    - wallet_transaction
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                wallet_transaction:
                  $ref: '#/components/schemas/WalletTransactionObjectExtended'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  wallet_transaction_updated:
    post:
      operationId: walletTransactionUpdated
      summary: A wallet transaction has been updated
      description: A wallet transaction has been updated
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the wallet transaction
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - wallet_transaction
              properties:
                webhook_type:
                  type: string
                  enum:
                    - wallet_transaction.updated
                object_type:
                  type: string
                  enum:
                    - wallet_transaction
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                wallet_transaction:
                  $ref: '#/components/schemas/WalletTransactionObjectExtended'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  wallet_transaction_payment_failure:
    post:
      operationId: walletTransactionPaymentFailure
      summary: A payment attempt for a wallet transaction has failed on a payment provider
      description: A payment attempt for a wallet transaction has failed on a payment provider
      parameters:
        - $ref: '#/components/parameters/webhook_signature'
        - $ref: '#/components/parameters/webhook_signature_algorithm'
        - $ref: '#/components/parameters/webhook_unique_key'
      requestBody:
        description: Details of the wallet transaction and of the provider error
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_type
                - object_type
                - organization_id
                - payment_provider_wallet_transaction_payment_error
              properties:
                webhook_type:
                  type: string
                  enum:
                    - wallet_transaction.payment_failure
                object_type:
                  type: string
                  enum:
                    - payment_provider_wallet_transaction_payment_error
                organization_id:
                  type: string
                  format: uuid
                  description: Unique identifier of the organization, created by Lago.
                  example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                payment_provider_wallet_transaction_payment_error:
                  $ref: '#/components/schemas/WalletTransactionPaymentFailureObject'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
components:
  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
    external_customer_id:
      name: external_customer_id
      in: query
      description: Unique identifier assigned to the customer in your application.
      required: false
      explode: true
      schema:
        type: string
        example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
    external_subscription_id:
      name: external_subscription_id
      in: query
      description: External subscription ID
      required: false
      explode: true
      schema:
        type: string
        example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
    months:
      name: months
      in: query
      description: Show data only for given number of months.
      required: false
      explode: true
      schema:
        type: integer
        example: 12
    external_customer_id_path:
      name: external_customer_id
      in: path
      description: The customer external unique identifier (provided by your own application)
      required: true
      schema:
        type: string
        example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
    payment_status:
      name: payment_status
      in: query
      description: Filter by payment status. Possible values are `pending`, `failed` or `succeeded`.
      required: false
      explode: true
      schema:
        type: string
        enum:
          - pending
          - failed
          - succeeded
        example: pending
    wallet_code:
      name: wallet_code
      in: path
      description: A unique wallet identifier within a customer. It is either set by the user at creation or auto-generated by Lago if not provided.
      required: true
      schema:
        type: string
        example: wallet-code
    lago_invoice_id:
      name: lago_id
      in: path
      description: Unique identifier assigned to the invoice within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the invoice's record within the Lago system.
      required: true
      schema:
        type: string
        format: uuid
        example: 1a901a90-1a90-1a90-1a90-1a901a901a90
    currency:
      name: currency
      in: query
      description: Filter the results by currency, expressed as an ISO 4217 code.
      required: false
      explode: true
      schema:
        type: string
        example: EUR
    plan_code:
      name: code
      in: path
      description: Code of the existing plan.
      required: true
      schema:
        type: string
        example: startup
    charge_code:
      name: charge_code
      in: path
      description: Code of the existing charge.
      required: true
      schema:
        type: string
        example: api_requests_charge
    charge_filter_id:
      name: filter_id
      in: path
      description: Unique identifier of the charge filter.
      required: true
      schema:
        type: string
        format: uuid
        example: 1a901a90-1a90-1a90-1a90-1a901a901a90
    fixed_charge_code:
      name: fixed_charge_code
      in: path
      description: Code of the existing fixed charge.
      required: true
      schema:
        type: string
        example: setup_fee_charge
    subscription_status:
      name: subscription_status
      in: query
      description: |
        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`, or `canceled`.
      required: false
      schema:
        type: string
        enum:
          - pending
          - active
          - terminated
          - canceled
        default: active
        example: active
    subscription_external_id_path:
      name: external_id
      in: path
      description: External ID of the existing subscription.
      required: true
      schema:
        type: string
        example: sub_1234567890
    webhook_signature:
      name: X-Lago-Signature
      in: header
      description: Signature of the webhook payload
      required: true
      schema:
        type: string
        example: "Ap¶5É¿\x9D\x9FΣ6ÐfV£Ä\x15\x15ºõÔõÔ[D\x8BæAâÿüÚ"
    webhook_signature_algorithm:
      name: X-Lago-Signature-Algorithm
      in: header
      description: Algorithm used to generate the signature
      required: true
      schema:
        type: string
        enum:
          - jwt
          - hmac
        example: hmac
    webhook_unique_key:
      name: X-Lago-Unique-Key
      in: header
      description: Unique id of the webhook. It can be used for idempotency
      required: true
      schema:
        type: string
        format: uuid
        example: 1a901a90-1a90-1a90-1a90-1a901a901a90
  schemas:
    Currency:
      type: string
      example: USD
      enum:
        - AED
        - AFN
        - ALL
        - AMD
        - ANG
        - AOA
        - ARS
        - AUD
        - AWG
        - AZN
        - BAM
        - BBD
        - BDT
        - BGN
        - BIF
        - BMD
        - BND
        - BOB
        - BRL
        - BSD
        - BWP
        - BYN
        - BZD
        - CAD
        - CDF
        - CHF
        - CLF
        - CLP
        - CNY
        - COP
        - CRC
        - CVE
        - CZK
        - DJF
        - DKK
        - DOP
        - DZD
        - EGP
        - ETB
        - EUR
        - FJD
        - FKP
        - GBP
        - GEL
        - GHS
        - GIP
        - GMD
        - GNF
        - GTQ
        - GYD
        - HKD
        - HNL
        - HRK
        - HTG
        - HUF
        - IDR
        - ILS
        - INR
        - ISK
        - JMD
        - JPY
        - KES
        - KGS
        - KHR
        - KMF
        - KRW
        - KYD
        - KZT
        - LAK
        - LBP
        - LKR
        - LRD
        - LSL
        - MAD
        - MDL
        - MGA
        - MKD
        - MMK
        - MNT
        - MOP
        - MRO
        - MUR
        - MVR
        - MWK
        - MXN
        - MYR
        - MZN
        - NAD
        - NGN
        - NIO
        - NOK
        - NPR
        - NZD
        - PAB
        - PEN
        - PGK
        - PHP
        - PKR
        - PLN
        - PYG
        - QAR
        - RON
        - RSD
        - RUB
        - RWF
        - SAR
        - SBD
        - SCR
        - SEK
        - SGD
        - SHP
        - SLL
        - SOS
        - SRD
        - STD
        - SZL
        - THB
        - TJS
        - TOP
        - TRY
        - TTD
        - TWD
        - TZS
        - UAH
        - UGX
        - USD
        - UYU
        - UZS
        - VND
        - VUV
        - WST
        - XAF
        - XCD
        - XOF
        - XPF
        - YER
        - ZAR
        - ZMW
    Country:
      type: string
      example: US
      enum:
        - AD
        - AE
        - AF
        - AG
        - AI
        - AL
        - AM
        - AO
        - AQ
        - AR
        - AS
        - AT
        - AU
        - AW
        - AX
        - AZ
        - BA
        - BB
        - BD
        - BE
        - BF
        - BG
        - BH
        - BI
        - BJ
        - BL
        - BM
        - BN
        - BO
        - BQ
        - BR
        - BS
        - BT
        - BV
        - BW
        - BY
        - BZ
        - CA
        - CC
        - CD
        - CF
        - CG
        - CH
        - CI
        - CK
        - CL
        - CM
        - CN
        - CO
        - CR
        - CU
        - CV
        - CW
        - CX
        - CY
        - CZ
        - DE
        - DJ
        - DK
        - DM
        - DO
        - DZ
        - EC
        - EE
        - EG
        - EH
        - ER
        - ES
        - ET
        - FI
        - FJ
        - FK
        - FM
        - FO
        - FR
        - GA
        - GB
        - GD
        - GE
        - GF
        - GG
        - GH
        - GI
        - GL
        - GM
        - GN
        - GP
        - GQ
        - GR
        - GS
        - GT
        - GU
        - GW
        - GY
        - HK
        - HM
        - HN
        - HR
        - HT
        - HU
        - ID
        - IE
        - IL
        - IM
        - IN
        - IO
        - IQ
        - IR
        - IS
        - IT
        - JE
        - JM
        - JO
        - JP
        - KE
        - KG
        - KH
        - KI
        - KM
        - KN
        - KP
        - KR
        - KW
        - KY
        - KZ
        - LA
        - LB
        - LC
        - LI
        - LK
        - LR
        - LS
        - LT
        - LU
        - LV
        - LY
        - MA
        - MC
        - MD
        - ME
        - MF
        - MG
        - MH
        - MK
        - ML
        - MM
        - MN
        - MO
        - MP
        - MQ
        - MR
        - MS
        - MT
        - MU
        - MV
        - MW
        - MX
        - MY
        - MZ
        - NA
        - NC
        - NE
        - NF
        - NG
        - NI
        - NL
        - 'NO'
        - NP
        - NR
        - NU
        - NZ
        - OM
        - PA
        - PE
        - PF
        - PG
        - PH
        - PK
        - PL
        - PM
        - PN
        - PR
        - PS
        - PT
        - PW
        - PY
        - QA
        - RE
        - RO
        - RS
        - RU
        - RW
        - SA
        - SB
        - SC
        - SD
        - SE
        - SG
        - SH
        - SI
        - SJ
        - SK
        - SL
        - SM
        - SN
        - SO
        - SR
        - SS
        - ST
        - SV
        - SX
        - SY
        - SZ
        - TC
        - TD
        - TF
        - TG
        - TH
        - TJ
        - TK
        - TL
        - TM
        - TN
        - TO
        - TR
        - TT
        - TV
        - TW
        - TZ
        - UA
        - UG
        - UM
        - US
        - UY
        - UZ
        - VA
        - VC
        - VE
        - VG
        - VI
        - VN
        - VU
        - WF
        - WS
        - YE
        - YT
        - ZA
        - ZM
        - ZW
    Timezone:
      type: string
      example: America/Los_Angeles
      enum:
        - UTC
        - Africa/Algiers
        - Africa/Cairo
        - Africa/Casablanca
        - Africa/Harare
        - Africa/Johannesburg
        - Africa/Monrovia
        - Africa/Nairobi
        - America/Argentina/Buenos_Aires
        - America/Bogota
        - America/Caracas
        - America/Chicago
        - America/Chihuahua
        - America/Denver
        - America/Guatemala
        - America/Guyana
        - America/Halifax
        - America/Indiana/Indianapolis
        - America/Juneau
        - America/La_Paz
        - America/Lima
        - America/Los_Angeles
        - America/Mazatlan
        - America/Mexico_City
        - America/Monterrey
        - America/Montevideo
        - America/New_York
        - America/Nuuk
        - America/Phoenix
        - America/Puerto_Rico
        - America/Regina
        - America/Santiago
        - America/Sao_Paulo
        - America/St_Johns
        - America/Tijuana
        - Asia/Almaty
        - Asia/Baghdad
        - Asia/Baku
        - Asia/Bangkok
        - Asia/Chongqing
        - Asia/Colombo
        - Asia/Dhaka
        - Asia/Hong_Kong
        - Asia/Irkutsk
        - Asia/Jakarta
        - Asia/Jerusalem
        - Asia/Kabul
        - Asia/Kamchatka
        - Asia/Karachi
        - Asia/Kathmandu
        - Asia/Kolkata
        - Asia/Krasnoyarsk
        - Asia/Kuala_Lumpur
        - Asia/Kuwait
        - Asia/Magadan
        - Asia/Muscat
        - Asia/Novosibirsk
        - Asia/Riyadh
        - Asia/Seoul
        - Asia/Shanghai
        - Asia/Singapore
        - Asia/Srednekolymsk
        - Asia/Taipei
        - Asia/Tashkent
        - Asia/Tbilisi
        - Asia/Tehran
        - Asia/Tokyo
        - Asia/Ulaanbaatar
        - Asia/Urumqi
        - Asia/Vladivostok
        - Asia/Yakutsk
        - Asia/Yangon
        - Asia/Yekaterinburg
        - Asia/Yerevan
        - Atlantic/Azores
        - Atlantic/Cape_Verde
        - Atlantic/South_Georgia
        - Australia/Adelaide
        - Australia/Brisbane
        - Australia/Darwin
        - Australia/Hobart
        - Australia/Melbourne
        - Australia/Perth
        - Australia/Sydney
        - Europe/Amsterdam
        - Europe/Athens
        - Europe/Belgrade
        - Europe/Berlin
        - Europe/Bratislava
        - Europe/Brussels
        - Europe/Bucharest
        - Europe/Budapest
        - Europe/Copenhagen
        - Europe/Dublin
        - Europe/Helsinki
        - Europe/Istanbul
        - Europe/Kaliningrad
        - Europe/Kyiv
        - Europe/Lisbon
        - Europe/Ljubljana
        - Europe/London
        - Europe/Madrid
        - Europe/Minsk
        - Europe/Moscow
        - Europe/Paris
        - Europe/Prague
        - Europe/Riga
        - Europe/Rome
        - Europe/Samara
        - Europe/Sarajevo
        - Europe/Skopje
        - Europe/Sofia
        - Europe/Stockholm
        - Europe/Tallinn
        - Europe/Vienna
        - Europe/Vilnius
        - Europe/Volgograd
        - Europe/Warsaw
        - Europe/Zagreb
        - Europe/Zurich
        - GMT+12
        - Pacific/Apia
        - Pacific/Auckland
        - Pacific/Chatham
        - Pacific/Fakaofo
        - Pacific/Fiji
        - Pacific/Guadalcanal
        - Pacific/Guam
        - Pacific/Honolulu
        - Pacific/Majuro
        - Pacific/Midway
        - Pacific/Noumea
        - Pacific/Pago_Pago
        - Pacific/Port_Moresby
        - Pacific/Tongatapu
    BillingEntityObject:
      type: object
      description: Billing entity object
      required:
        - lago_id
        - code
        - name
        - default_currency
        - document_locale
        - document_numbering
        - finalize_zero_amount_invoice
        - invoice_grace_period
        - net_payment_term
        - timezone
        - created_at
        - updated_at
      properties:
        lago_id:
          type: string
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: A unique identifier for the billing entity in the Lago application
        code:
          type: string
          example: acme_corp
          description: The unique code of the billing entity
        name:
          type: string
          example: Acme Corp
          description: The name of the billing entity
        default_currency:
          $ref: '#/components/schemas/Currency'
          description: The default currency of the billing entity
          example: USD
        document_locale:
          type: string
          example: en
          description: The language of the documents generated for this billing entity
        document_numbering:
          type: string
          enum:
            - per_customer
            - per_billing_entity
          description: |-
            The type of document numbering for this billing entity:
            - `per_customer`: document numbers are unique per customer
            - `per_billing_entity`: document numbers are unique per billing entity
          example: per_customer
        document_number_prefix:
          type:
            - string
            - 'null'
          example: ABC-123
          description: The prefix used in document numbers for this billing entity
        finalize_zero_amount_invoice:
          type: boolean
          example: true
          description: Whether to finalize invoices with zero amount for this billing entity
        invoice_footer:
          type:
            - string
            - 'null'
          example: Thank you for your business
          description: The footer text to be displayed on invoices for this billing entity
        invoice_grace_period:
          type: integer
          example: 0
          description: The grace period (in days) for invoice finalization
        subscription_invoice_issuing_date_anchor:
          type: string
          description: Defines whether the issuing date follows the current billing period's end date or the next period starting date.
          enum:
            - current_period_end
            - next_period_start
          default: next_period_start
        subscription_invoice_issuing_date_adjustment:
          type: string
          description: The logic applied on top of the subscription_invoice_issuing_date_anchor rule. You can opt to use the invoice finalization date, that includes any configured grace period.
          enum:
            - align_with_finalization_date
            - keep_anchor
          default: align_with_finalization_date
        is_default:
          type: boolean
          example: false
          description: Whether this billing entity is the default billing entity for the organization. Default billing entity will be used as fallback in services if no billing entity is specified when billing_entity is not provided. Default billing entity is the billing entity that will be used to generate invoices if no billing entity is specified when invoice is created. is the oldest active billing entity and this flag cannot be changed
        net_payment_term:
          type: integer
          example: 0
          description: The net payment term (in days) for this billing entity
        address_line1:
          type:
            - string
            - 'null'
          example: 5230 Penfield Ave
          description: The first line of the billing address
        address_line2:
          type:
            - string
            - 'null'
          example: Suite 100
          description: The second line of the billing address
        city:
          type:
            - string
            - 'null'
          example: Woodland Hills
          description: The city of the billing address
        state:
          type:
            - string
            - 'null'
          example: CA
          description: The state of the billing address
        country:
          $ref: '#/components/schemas/Country'
          description: The country code of the billing address
          nullable: true
        zipcode:
          type:
            - string
            - 'null'
          example: '91364'
          description: The zipcode of the billing address
        email:
          type:
            - string
            - 'null'
          format: email
          example: billing@acme.com
          description: The email address of the billing entity
        legal_name:
          type:
            - string
            - 'null'
          example: Acme Corporation
          description: The legal name of the billing entity
        legal_number:
          type:
            - string
            - 'null'
          example: US123456789
          description: The legal registration number of the billing entity
        tax_identification_number:
          type:
            - string
            - 'null'
          example: EU123456789
          description: The tax identification number of the billing entity
        timezone:
          $ref: '#/components/schemas/Timezone'
          description: The timezone of the billing entity
          example: UTC
        email_settings:
          type: array
          items:
            type: string
            enum:
              - invoice.finalized
              - credit_note.created
              - payment_receipt.created
          description: The email notification settings for this billing entity
        eu_tax_management:
          type: boolean
          example: false
          description: Whether EU tax management is enabled for this billing entity
        logo_url:
          type:
            - string
            - 'null'
          format: uri
          example: https://getlago.com/logo.png
          description: The URL of the billing entity's logo
        created_at:
          type: string
          format: date-time
          example: '2022-04-29T08:59:51Z'
          description: The date and time when the billing entity was created
        updated_at:
          type: string
          format: date-time
          example: '2022-04-29T08:59:51Z'
          description: The date and time when the billing entity was last updated
    ApiErrorUnauthorized:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: integer
          format: int32
          example: 401
        error:
          type: string
          example: Unauthorized
    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
    BillingEntityCreateInput:
      type: object
      description: Billing entity create input
      required:
        - billing_entity
      properties:
        billing_entity:
          type: object
          required:
            - code
            - name
          properties:
            code:
              type: string
              example: acme_corp
              description: The unique code of the billing entity
            name:
              type: string
              example: Acme Corp
              description: The name of the billing entity
            default_currency:
              $ref: '#/components/schemas/Currency'
              description: The default currency of the billing entity
              example: USD
            document_numbering:
              type: string
              enum:
                - per_customer
                - per_billing_entity
              description: |-
                The type of document numbering for this billing entity:
                - `per_customer`: document numbers are unique per customer
                - `per_billing_entity`: document numbers are unique per billing entity
            document_number_prefix:
              type:
                - string
                - 'null'
              example: ABC-123
              description: The prefix used in document numbers for this billing entity
            finalize_zero_amount_invoice:
              type: boolean
              example: true
              description: Whether to finalize invoices with zero amount for this billing entity
            billing_configuration:
              type: object
              properties:
                invoice_footer:
                  type: string
                  example: Thank you for your business
                  description: The footer text to be displayed on invoices for this billing entity
                document_locale:
                  type: string
                  example: en
                  description: The language of the documents generated for this billing entity
                invoice_grace_period:
                  type: integer
                  example: 0
                  description: The grace period (in days) for invoice finalization
                subscription_invoice_issuing_date_anchor:
                  type: string
                  description: Defines whether the issuing date follows the current billing period's end date or the next period starting date.
                  enum:
                    - current_period_end
                    - next_period_start
                  default: next_period_start
                subscription_invoice_issuing_date_adjustment:
                  type: string
                  description: The logic applied on top of the subscription_invoice_issuing_date_anchor rule. You can opt to use the invoice finalization date, that includes any configured grace period.
                  enum:
                    - align_with_finalization_date
                    - keep_anchor
                  default: align_with_finalization_date
            net_payment_term:
              type: integer
              example: 0
              description: The net payment term (in days) for this billing entity
            address_line1:
              type:
                - string
                - 'null'
              example: 5230 Penfield Ave
              description: The first line of the billing address
            address_line2:
              type:
                - string
                - 'null'
              example: Suite 100
              description: The second line of the billing address
            city:
              type:
                - string
                - 'null'
              example: Woodland Hills
              description: The city of the billing address
            state:
              type:
                - string
                - 'null'
              example: CA
              description: The state of the billing address
            country:
              $ref: '#/components/schemas/Country'
              description: The country code of the billing address
              nullable: true
            zipcode:
              type:
                - string
                - 'null'
              example: '91364'
              description: The zipcode of the billing address
            email:
              type:
                - string
                - 'null'
              format: email
              example: billing@acme.com
              description: The email address of the billing entity
            legal_name:
              type:
                - string
                - 'null'
              example: Acme Corporation
              description: The legal name of the billing entity
            legal_number:
              type:
                - string
                - 'null'
              example: US123456789
              description: The legal registration number of the billing entity
            tax_identification_number:
              type:
                - string
                - 'null'
              example: EU123456789
              description: The tax identification number of the billing entity
            timezone:
              $ref: '#/components/schemas/Timezone'
              description: The timezone of the billing entity
              example: UTC
            email_settings:
              type: array
              items:
                type: string
                enum:
                  - invoice.finalized
                  - credit_note.created
              description: The email notification settings for this billing entity
            eu_tax_management:
              type: boolean
              example: false
              description: Whether EU tax management is enabled for this billing entity
            logo:
              type:
                - string
                - 'null'
              format: uri
              example: data:image/png;base64,...
              description: The base64 encoded logo image for the billing entity
    ApiErrorBadRequest:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: integer
          format: int32
          example: 400
        error:
          type: string
          example: Bad request
    ApiErrorForbidden:
      type: object
      required:
        - status
        - error
        - code
      properties:
        status:
          type: integer
          format: int32
          example: 403
        error:
          type: string
          example: Forbidden
        code:
          type: string
          example: feature_unavailable
    TaxObject:
      type: object
      required:
        - lago_id
        - name
        - code
        - rate
        - applied_to_organization
        - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the tax, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        name:
          type: string
          description: Name of the tax.
          example: TVA
        code:
          type: string
          description: Unique code used to identify the tax associated with the API request.
          example: french_standard_vat
        description:
          type:
            - string
            - 'null'
          description: Internal description of the tax
          example: French standard VAT
        rate:
          type: number
          description: The percentage rate of the tax
          example: 20
        applied_to_organization:
          type: boolean
          deprecated: true
          description: '**Deprecated.** This field will be removed in a future version. When set to true, it applies the tax to the organization''s default billing entity. To apply or remove a tax from any billing entity (including the default one), please use the `PUT /billing_entities/:code` endpoint instead.'
          example: true
        created_at:
          type: string
          format: date-time
          description: Creation date of the tax.
          example: '2023-07-06T14:35:58Z'
    InvoiceCustomSectionObject:
      type: object
      required:
        - lago_id
        - name
        - code
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier for the invoice custom section in the Lago application, generated by Lago to ensure record uniqueness within the system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        name:
          type: string
          description: Name of the invoice custom section.
          example: EU Bank Details
        code:
          type: string
          description: Unique code identifying the invoice custom section for the API request.
          example: eu_bank_details
        description:
          type: string
          description: Internal description of the invoice custom section.
          example: This section contains the bank details for EU customers.
        details:
          type: string
          description: The value shown on the invoice PDF.
          example: 'Bank Name: Lago Bank, IBAN: FR7630004000031234567890143'
        display_name:
          type: string
          description: The name of the invoice custom section displayed on the invoice.
          example: 'Bank Details:'
        applied_to_organization:
          type: boolean
          deprecated: true
          description: '**Deprecated.** This field will be removed in a future version. When set to true, it applies the invoice custom section to the organization''s default billing entity. To apply or remove an invoice custom section from any billing entity (including the default one), please use the `PUT /billing_entities/:code` endpoint instead.'
          example: true
        organization_id:
          type: string
          format: uuid
          description: Unique identifier for the organization associated with the invoice custom section.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        created_at:
          type: string
          format: date-time
          description: Creation date of the tax.
          example: '2023-07-06T14:35:58Z'
    BillingEntityObjectExtended:
      allOf:
        - $ref: '#/components/schemas/BillingEntityObject'
        - type: object
          properties:
            taxes:
              type: array
              items:
                $ref: '#/components/schemas/TaxObject'
            selected_invoice_custom_sections:
              type: array
              items:
                $ref: '#/components/schemas/InvoiceCustomSectionObject'
    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
    TaxCodes:
      type: array
      items:
        type: string
      description: List of unique code used to identify the taxes.
      example:
        - french_standard_vat
    BillingEntityUpdateInput:
      type: object
      description: Billing entity update input
      properties:
        name:
          type: string
          example: Acme Corp
          description: The name of the billing entity
        default_currency:
          $ref: '#/components/schemas/Currency'
          description: The default currency of the billing entity
          example: USD
        document_numbering:
          type: string
          enum:
            - per_customer
            - per_billing_entity
          description: |-
            The type of document numbering for this billing entity:
            - `per_customer`: document numbers are unique per customer
            - `per_billing_entity`: document numbers are unique per billing entity
        document_number_prefix:
          type:
            - string
            - 'null'
          example: ABC-123
          description: The prefix used in document numbers for this billing entity
        finalize_zero_amount_invoice:
          type: boolean
          example: true
          description: Whether to finalize invoices with zero amount for this billing entity
        billing_configuration:
          type: object
          properties:
            invoice_footer:
              type: string
              example: Thank you for your business
              description: The footer text to be displayed on invoices for this billing entity
            document_locale:
              type: string
              example: en
              description: The language of the documents generated for this billing entity
            invoice_grace_period:
              type: integer
              example: 0
              description: The grace period (in days) for invoice finalization
            subscription_invoice_issuing_date_anchor:
              type: string
              description: Defines whether the issuing date follows the current billing period's end date or the next period starting date.
              enum:
                - current_period_end
                - next_period_start
              default: next_period_start
            subscription_invoice_issuing_date_adjustment:
              type: string
              description: The logic applied on top of the subscription_invoice_issuing_date_anchor rule. You can opt to use the invoice finalization date, that includes any configured grace period.
              enum:
                - align_with_finalization_date
                - keep_anchor
              default: align_with_finalization_date
        net_payment_term:
          type: integer
          example: 0
          description: The net payment term (in days) for this billing entity
        address_line1:
          type:
            - string
            - 'null'
          example: 5230 Penfield Ave
          description: The first line of the billing address
        address_line2:
          type:
            - string
            - 'null'
          example: Suite 100
          description: The second line of the billing address
        city:
          type:
            - string
            - 'null'
          example: Woodland Hills
          description: The city of the billing address
        state:
          type:
            - string
            - 'null'
          example: CA
          description: The state of the billing address
        country:
          $ref: '#/components/schemas/Country'
          description: The country code of the billing address
          nullable: true
        zipcode:
          type:
            - string
            - 'null'
          example: '91364'
          description: The zipcode of the billing address
        email:
          type:
            - string
            - 'null'
          format: email
          example: billing@acme.com
          description: The email address of the billing entity
        legal_name:
          type:
            - string
            - 'null'
          example: Acme Corporation
          description: The legal name of the billing entity
        legal_number:
          type:
            - string
            - 'null'
          example: US123456789
          description: The legal registration number of the billing entity
        tax_identification_number:
          type:
            - string
            - 'null'
          example: EU123456789
          description: The tax identification number of the billing entity
        timezone:
          $ref: '#/components/schemas/Timezone'
          description: The timezone of the billing entity
          example: UTC
        tax_codes:
          $ref: '#/components/schemas/TaxCodes'
          description: The tax codes that should be associated with this billing entity
        email_settings:
          type: array
          items:
            type: string
            enum:
              - invoice.finalized
              - credit_note.created
          description: The email notification settings for this billing entity
        eu_tax_management:
          type: boolean
          example: false
          description: Whether EU tax management is enabled for this billing entity
        logo:
          type:
            - string
            - 'null'
          format: uri
          example: data:image/png;base64,...
          description: The base64 encoded logo image for the billing entity. Sending "null" will remove the logo, if any exist.
        invoice_custom_section_codes:
          type: array
          items:
            type: string
          example:
            - custom_section_1
            - custom_section_2
          description: The codes of the invoice custom section that should be associated with this billing entity
    ActivityLogObject:
      type: object
      required:
        - activity_id
        - activity_source
        - activity_type
        - logged_at
        - resource_id
        - resource_type
        - organization_id
        - created_at
      properties:
        activity_id:
          type: string
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: Unique identifier assigned to the activity log within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the activity log record within the Lago system
        user_email:
          type:
            - string
            - 'null'
          format: email
          example: dinesh@piedpiper.test
          description: The email of the user who performed the activity
        activity_type:
          type: string
          example: billing_metric.created
          description: This field stores the actitivy action that was performed to the activity_object.
        activity_source:
          type: string
          example: api
          enum:
            - api
            - front
            - system
          description: This field represents the source of the activity log, the interaction source that triggered the action.
        activity_object:
          type:
            - object
            - 'null'
          format: object
          example:
            lago_id: dad68bc7-c01a-4ad8-a87b-13e78693a5bc
            plan_id: b9155544-e261-4e92-b54e-f65d7609294c
          description: This field represents the final state of the object that the action was applied.
        activity_object_changes:
          type:
            - object
            - 'null'
          format: object
          example:
            plan_id:
              - null
              - b9155544-e261-4e92-b54e-f65d7609294c
        external_customer_id:
          type:
            - string
            - 'null'
          description: The customer external unique identifier (provided by your own application)
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        external_subscription_id:
          type:
            - string
            - 'null'
          description: Unique identifier assigned to the subscription in your application.
          example: external_id
        resource_id:
          type: string
          description: The resource id of the object that the action was applied.
          format: uuid
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        resource_type:
          type: string
          description: The resource type of the resource_id record.
          example: BillableMetric
        organization_id:
          type: string
          format: uuid
          description: Unique identifier for the organization associated with the activity log.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        logged_at:
          type: string
          format: date-time
          example: '2025-03-31T12:31:44Z'
          description: The logged date of the activity, presented in the ISO 8601 datetime format, specifically in Coordinated Universal Time (UTC). It provides the precise timestamp of when the event's record was created within the Lago application
        created_at:
          type: string
          format: date-time
          example: '2022-04-29T08:59:51Z'
          description: The creation date of the activity record in the Lago application, presented in the ISO 8601 datetime format, specifically in Coordinated Universal Time (UTC). It provides the precise timestamp of when the event's record was created within the Lago application
    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
    ActivityLogsPaginated:
      type: object
      required:
        - activity_logs
        - meta
      properties:
        activity_logs:
          type: array
          items:
            $ref: '#/components/schemas/ActivityLogObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    ActivityLog:
      type: object
      required:
        - activity_log
      properties:
        activity_log:
          $ref: '#/components/schemas/ActivityLogObject'
    AddOnObject:
      type: object
      required:
        - lago_id
        - name
        - invoice_display_name
        - code
        - amount_cents
        - amount_currency
        - description
        - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the add-on, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        name:
          type: string
          description: The name of the add-on.
          example: Setup Fee
        invoice_display_name:
          type:
            - string
            - 'null'
          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 Fee (SF1)
        code:
          type: string
          description: Unique code used to identify the add-on.
          example: setup_fee
        amount_cents:
          type: integer
          description: The cost of the add-on in cents, excluding any applicable taxes, that is billed to a customer. By creating a one-off invoice, you will be able to override this value.
          example: 50000
        amount_currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of the add-on.
          example: USD
        description:
          type:
            - string
            - 'null'
          description: The description of the add-on.
          example: Implementation fee for new customers.
        created_at:
          type: string
          format: date-time
          description: The date and time when the add-on was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the add-on was initially created.
          example: '2022-04-29T08:59:51Z'
        taxes:
          type: array
          description: All taxes applied to the add-on.
          items:
            $ref: '#/components/schemas/TaxObject'
    AddOnsPaginated:
      type: object
      required:
        - add_ons
        - meta
      properties:
        add_ons:
          type: array
          items:
            $ref: '#/components/schemas/AddOnObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    AddOnBaseInput:
      type: object
      properties:
        name:
          type: string
          description: The name of the add-on.
          example: Setup Fee
        invoice_display_name:
          type:
            - string
            - 'null'
          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 Fee (SF1)
        code:
          type: string
          description: Unique code used to identify the add-on.
          example: setup_fee
        amount_cents:
          type: integer
          description: The cost of the add-on in cents, excluding any applicable taxes, that is billed to a customer. By creating a one-off invoice, you will be able to override this value.
          example: 50000
        amount_currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of the add-on.
          example: USD
        description:
          type:
            - string
            - 'null'
          description: The description of the add-on.
          example: Implementation fee for new customers.
        tax_codes:
          $ref: '#/components/schemas/TaxCodes'
    AddOnCreateInput:
      type: object
      required:
        - add_on
      properties:
        add_on:
          $ref: '#/components/schemas/AddOnBaseInput'
          required:
            - name
            - code
            - amount_cents
            - amount_currency
    AddOn:
      type: object
      required:
        - add_on
      properties:
        add_on:
          $ref: '#/components/schemas/AddOnObject'
    AddOnUpdateInput:
      type: object
      required:
        - add_on
      properties:
        add_on:
          $ref: '#/components/schemas/AddOnBaseInput'
    ApiLogObject:
      type: object
      required:
        - api_version
        - client
        - http_method
        - http_status
        - logged_at
        - request_body
        - request_origin
        - request_path
        - created_at
        - request_id
      properties:
        api_version:
          type: string
          example: v1
          description: Lago API version used in the request.
        client:
          type: string
          example: Lago Ruby v1.26.0
          description: The client used to make the request to the API.
        http_method:
          type: string
          example: post
          enum:
            - post
            - put
            - delete
          description: This field represents the HTTP method of the request.
        http_status:
          type: integer
          example: 200
          description: This field represents the HTTP status of the requests.
        logged_at:
          type: string
          format: date-time
          example: '2025-03-31T12:31:44Z'
          description: The logged date of the api log, presented in the ISO 8601 datetime format, specifically in Coordinated Universal Time (UTC). It provides the precise timestamp of when the event's record was created within the Lago application
        request_body:
          type: string
          format: object
          example: '{ "billable_metric": { "name": "Storage", "code": "storage" } }'
        request_origin:
          type: string
          description: This field represents the API origin of the requested URL
          example: https://app.lago.dev/
        request_path:
          type: string
          description: This field represents the API path of the requested URL
          example: /billable_metrics
        created_at:
          type: string
          format: date-time
          example: '2022-04-29T08:59:51Z'
          description: The creation date of the api log record in the Lago application, presented in the ISO 8601 datetime format, specifically in Coordinated Universal Time (UTC). It provides the precise timestamp of when the event's record was created within the Lago application
        request_id:
          type: string
          format: uuid
          description: Unique identifier for the api log.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        request_response:
          type: string
          format: object
          example: '{ "lago_id": "b9155544-e261-4e92-b54e-f65d7609294c", ... }'
    ApiLogsPaginated:
      type: object
      required:
        - api_logs
        - meta
      properties:
        api_logs:
          type: array
          items:
            $ref: '#/components/schemas/ApiLogObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    ApiLog:
      type: object
      required:
        - api_log
      properties:
        api_log:
          $ref: '#/components/schemas/ApiLogObject'
    GrossRevenueObject:
      type: object
      required:
        - month
        - amount_cents
        - currency
        - invoices_count
      properties:
        month:
          type: string
          description: Identifies the month to analyze revenue.
          example: '2023-11-01T00:00:00.000Z'
        amount_cents:
          type: integer
          description: The total amount of revenue for a period, expressed in cents.
          example: 50000
        currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of revenue analytics. Format must be ISO 4217.
          example: USD
        invoices_count:
          type: integer
          description: Contains invoices count.
          example: 10
    GrossRevenues:
      type: object
      required:
        - gross_revenues
      properties:
        gross_revenues:
          type: array
          items:
            $ref: '#/components/schemas/GrossRevenueObject'
    InvoiceCollectionObject:
      type: object
      required:
        - month
        - invoices_count
      properties:
        month:
          type: string
          description: Identifies the month to analyze revenue.
          example: '2023-11-01T00:00:00.000Z'
        payment_status:
          type: string
          enum:
            - pending
            - succeeded
            - failed
          description: The payment status of the invoices.
          example: succeeded
        invoices_count:
          type: integer
          description: Contains invoices count.
          example: 10
        amount_cents:
          type: integer
          description: The total amount of revenue for a period, expressed in cents.
          example: 50000
        currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of revenue analytics. Format must be ISO 4217.
          example: USD
    InvoiceCollections:
      type: object
      required:
        - invoice_collections
      properties:
        invoice_collections:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceCollectionObject'
    InvoicedUsageObject:
      type: object
      required:
        - month
        - amount_cents
        - currency
      properties:
        month:
          type: string
          description: Identifies the month to analyze revenue.
          example: '2023-11-01T00:00:00.000Z'
        code:
          type: string
          description: The code of the usage-based billable metrics.
          example: code1
        amount_cents:
          type: integer
          description: The total amount of revenue for a period, expressed in cents.
          example: 50000
        currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of revenue analytics. Format must be ISO 4217.
          example: USD
    InvoicedUsages:
      type: object
      required:
        - invoiced_usages
      properties:
        invoiced_usages:
          type: array
          items:
            $ref: '#/components/schemas/InvoicedUsageObject'
    MrrObject:
      type: object
      required:
        - month
        - amount_cents
        - currency
      properties:
        month:
          type: string
          description: Identifies the month to analyze MRR.
          example: '2023-11-01T00:00:00.000Z'
        amount_cents:
          type: integer
          description: The total amount of MRR, expressed in cents.
          example: 50000
        currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of MRR analytics. Format must be ISO 4217.
          example: USD
    Mrrs:
      type: object
      required:
        - mrrs
      properties:
        mrrs:
          type: array
          items:
            $ref: '#/components/schemas/MrrObject'
    OverdueBalanceObject:
      type: object
      required:
        - month
        - amount_cents
        - currency
        - lago_invoice_ids
      properties:
        month:
          type: string
          description: Identifies the month to analyze revenue.
          example: '2023-11-01T00:00:00.000Z'
        amount_cents:
          type: integer
          description: The total amount of revenue for a period, expressed in cents.
          example: 50000
        currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of revenue analytics. Format must be ISO 4217.
          example: USD
        lago_invoice_ids:
          type: array
          items:
            type: string
            format: uuid
          description: The Lago invoice IDs associated with the revenue.
          example:
            - 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
    OverdueBalances:
      type: object
      required:
        - overdue_balances
      properties:
        overdue_balances:
          type: array
          items:
            $ref: '#/components/schemas/OverdueBalanceObject'
    UsageObject:
      type: object
      required:
        - organization_id
        - amount_cents
        - amount_currency
      properties:
        organization_id:
          type: string
          format: uuid
          description: The unique identifier of the organization for which the usage analytics is calculated.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        start_of_period_dt:
          type: string
          format: date
          description: The start date of the period for which the usage analytics is calculated.
          example: '2023-11-01'
        end_of_period_dt:
          type: string
          format: date
          description: The end date of the period for which the usage analytics is calculated.
          example: '2023-11-30'
        amount_currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of usage analytics. Format must be ISO 4217.
          example: USD
        amount_cents:
          type: integer
          description: The total amount for usages for a period, expressed in cents.
          example: 50000
        billable_metric_code:
          type: string
          description: The code of the usage-based billable metrics.
          example: code1
        units:
          type: string
          description: The total number of units for the usage-based billable metrics.
          pattern: ^[0-9]+.?[0-9]*$
          example: '1.0'
        is_billable_metric_deleted:
          type: boolean
          description: Indicates whether the billable metric associated with the usage is deleted.
          example: false
    Usages:
      type: object
      required:
        - usages
      properties:
        usages:
          type: array
          items:
            $ref: '#/components/schemas/UsageObject'
    CurrencyOrNull:
      type:
        - string
        - 'null'
      example: USD
      enum:
        - null
        - AED
        - AFN
        - ALL
        - AMD
        - ANG
        - AOA
        - ARS
        - AUD
        - AWG
        - AZN
        - BAM
        - BBD
        - BDT
        - BGN
        - BIF
        - BMD
        - BND
        - BOB
        - BRL
        - BSD
        - BWP
        - BYN
        - BZD
        - CAD
        - CDF
        - CHF
        - CLF
        - CLP
        - CNY
        - COP
        - CRC
        - CVE
        - CZK
        - DJF
        - DKK
        - DOP
        - DZD
        - EGP
        - ETB
        - EUR
        - FJD
        - FKP
        - GBP
        - GEL
        - GIP
        - GMD
        - GNF
        - GTQ
        - GYD
        - HKD
        - HNL
        - HRK
        - HTG
        - HUF
        - IDR
        - ILS
        - INR
        - ISK
        - JMD
        - JPY
        - KES
        - KGS
        - KHR
        - KMF
        - KRW
        - KYD
        - KZT
        - LAK
        - LBP
        - LKR
        - LRD
        - LSL
        - MAD
        - MDL
        - MGA
        - MKD
        - MMK
        - MNT
        - MOP
        - MRO
        - MUR
        - MVR
        - MWK
        - MXN
        - MYR
        - MZN
        - NAD
        - NGN
        - NIO
        - NOK
        - NPR
        - NZD
        - PAB
        - PEN
        - PGK
        - PHP
        - PKR
        - PLN
        - PYG
        - QAR
        - RON
        - RSD
        - RUB
        - RWF
        - SAR
        - SBD
        - SCR
        - SEK
        - SGD
        - SHP
        - SLL
        - SOS
        - SRD
        - STD
        - SZL
        - THB
        - TJS
        - TOP
        - TRY
        - TTD
        - TWD
        - TZS
        - UAH
        - UGX
        - USD
        - UYU
        - UZS
        - VND
        - VUV
        - WST
        - XAF
        - XCD
        - XOF
        - XPF
        - YER
        - ZAR
        - ZMW
    AppliedCouponObject:
      type: object
      required:
        - lago_id
        - lago_coupon_id
        - coupon_code
        - coupon_name
        - external_customer_id
        - lago_customer_id
        - status
        - frequency
        - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the applied coupon, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_coupon_id:
          type: string
          format: uuid
          description: Unique identifier of the coupon, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        coupon_code:
          type: string
          description: Unique code used to identify the coupon.
          example: startup_deal
        coupon_name:
          type: string
          description: The name of the coupon.
          example: Startup Deal
        coupon_status:
          type: string
          enum:
            - active
            - terminated
          description: The status of the parent coupon. Can be either `active` or `terminated`.
          example: active
        coupon_deleted_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time when the parent coupon was deleted. If null, the coupon still exists. It is expressed in UTC format according to the ISO 8601 datetime standard.
          example: '2022-04-29T08:59:51Z'
        lago_customer_id:
          type: string
          format: uuid
          description: Unique identifier of the customer, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_customer_id:
          type: string
          description: The customer external unique identifier (provided by your own application)
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        status:
          type: string
          enum:
            - active
            - terminated
          description: The status of the coupon. Can be either `active` or `terminated`.
          example: active
        amount_cents:
          type:
            - integer
            - 'null'
          description: The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type.
          example: 2000
        amount_cents_remaining:
          type:
            - integer
            - 'null'
          description: The remaining amount in cents for a `fixed_amount` coupon with a frequency set to `once`. This field indicates the remaining balance or value that can still be utilized from the coupon.
          example: 50
        amount_currency:
          $ref: '#/components/schemas/CurrencyOrNull'
          description: The currency of the coupon. This field is required only for coupon with `fixed_amount` type.
          example: EUR
        percentage_rate:
          type:
            - string
            - 'null'
          pattern: ^[0-9]+.?[0-9]*$
          description: The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type.
          example: null
        frequency:
          type: string
          enum:
            - once
            - recurring
            - forever
          description: |-
            The type of frequency for the coupon. It can have three possible values: `once`, `recurring` or `forever`.

            - If set to `once`, the coupon is applicable only for a single use.
            - If set to `recurring`, the coupon can be used multiple times for recurring billing periods.
            - If set to `forever`, the coupon has unlimited usage and can be applied indefinitely.
          example: recurring
        frequency_duration:
          type:
            - integer
            - 'null'
          description: Specifies the number of billing periods to which the coupon applies. This field is required only for coupons with a `recurring` frequency type
          example: 3
        frequency_duration_remaining:
          type:
            - integer
            - 'null'
          description: The remaining number of billing periods to which the coupon is applicable. This field determines the remaining usage or availability of the coupon based on the remaining billing periods.
          example: 1
        expiration_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time after which the coupon will stop applying to customer's invoices. Once the expiration date is reached, the coupon will no longer be applicable, and any further invoices generated for the customer will not include the coupon discount.
          example: '2022-04-29T08:59:51Z'
        created_at:
          type: string
          format: date-time
          description: The date and time when the coupon was assigned to a customer. It is expressed in UTC format according to the ISO 8601 datetime standard.
          example: '2022-04-29T08:59:51Z'
        terminated_at:
          type:
            - string
            - 'null'
          format: date-time
          description: This field indicates the specific moment when the coupon amount is fully utilized or when the coupon is removed from the customer's coupon list. It is expressed in UTC format according to the ISO 8601 datetime standard.
          example: '2022-04-29T08:59:51Z'
    CreditObject:
      type: object
      required:
        - lago_id
        - item
        - amount_cents
        - amount_currency
        - invoice
        - before_taxes
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the credit within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the credit's item record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        amount_cents:
          type: integer
          description: The amount of credit associated with the invoice, expressed in cents.
          example: 1200
        amount_currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of the credit.
          example: EUR
        before_taxes:
          type: boolean
          description: Indicates whether the credit is applied on the amount before taxes (coupons) or after taxes (credit notes). This flag helps determine the order in which credits are applied to the invoice calculation
          example: false
        item:
          type: object
          description: The item attached to the credit.
          required:
            - lago_item_id
            - type
            - code
            - name
          properties:
            lago_item_id:
              type: string
              format: uuid
              description: Unique identifier assigned to the credit item within the Lago application.
              example: 1a901a90-1a90-1a90-1a90-1a901a901a90
            type:
              type: string
              enum:
                - coupon
                - credit_note
                - invoice
              description: The type of credit applied. Possible values are `coupon`, `credit_note` or `invoice` (for `progressive_billing` invoice).
              example: coupon
            code:
              type: string
              description: The code of the credit applied. It can be the code of the coupon attached to the credit, the credit note's number or the `progressive_billing` invoice number.
              example: startup_deal
            name:
              type: string
              description: The name of the credit applied. It can be the name of the coupon attached to the credit, the initial invoice's number linked to the credit note or the `progressive_billing` invoice number.
              example: Startup Deal
        invoice:
          type: object
          required:
            - lago_id
            - payment_status
          properties:
            lago_id:
              type: string
              format: uuid
              example: 1a901a90-1a90-1a90-1a90-1a901a901a90
            payment_status:
              type: string
              enum:
                - pending
                - succeeded
                - failed
              example: succeeded
    AppliedCouponObjectExtended:
      allOf:
        - $ref: '#/components/schemas/AppliedCouponObject'
        - type: object
          required:
            - credits
          properties:
            credits:
              type: array
              items:
                $ref: '#/components/schemas/CreditObject'
    AppliedCouponsPaginated:
      type: object
      required:
        - applied_coupons
        - meta
      properties:
        applied_coupons:
          type: array
          items:
            $ref: '#/components/schemas/AppliedCouponObjectExtended'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    AppliedCouponInput:
      type: object
      required:
        - applied_coupon
      properties:
        applied_coupon:
          type: object
          required:
            - external_customer_id
            - coupon_code
          properties:
            external_customer_id:
              type: string
              description: The customer external unique identifier (provided by your own application)
              example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
            coupon_code:
              type: string
              description: Unique code used to identify the coupon.
              example: startup_deal
            frequency:
              type:
                - string
                - 'null'
              enum:
                - once
                - recurring
                - forever
                - null
              description: |-
                The type of frequency for the coupon. It can have three possible values: `once`, `recurring` or `forever`.

                - If set to `once`, the coupon is applicable only for a single use.
                - If set to `recurring`, the coupon can be used multiple times for recurring billing periods.
                - If set to `forever`, the coupon has unlimited usage and can be applied indefinitely.
              example: recurring
            frequency_duration:
              type:
                - integer
                - 'null'
              description: Specifies the number of billing periods to which the coupon applies. This field is required only for coupons with a `recurring` frequency type
              example: 3
            amount_cents:
              type:
                - integer
                - 'null'
              description: The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type.
              example: 2000
            amount_currency:
              $ref: '#/components/schemas/CurrencyOrNull'
              description: The currency of the coupon. This field is required only for coupon with `fixed_amount` type.
              example: EUR
            percentage_rate:
              type:
                - string
                - 'null'
              pattern: ^[0-9]+.?[0-9]*$
              description: The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type.
              example: null
    AppliedCoupon:
      type: object
      required:
        - applied_coupon
      properties:
        applied_coupon:
          $ref: '#/components/schemas/AppliedCouponObject'
    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
    BillableMetricObject:
      type: object
      required:
        - lago_id
        - name
        - code
        - aggregation_type
        - recurring
        - created_at
      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
          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.
        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` aggregation type. It serves to adjust the aggregation result by assigning weights and proration to the result based on time intervals. When this field is not provided, the default time interval is assumed to be in `seconds`.
        filters:
          type: array
          items:
            $ref: '#/components/schemas/BillableMetricFilterObject'
    BillableMetricsPaginated:
      type: object
      required:
        - billable_metrics
        - meta
      properties:
        billable_metrics:
          type: array
          items:
            $ref: '#/components/schemas/BillableMetricObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    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
    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((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.
            Round is accepting an optional second parameter to specify the number of decimal.
        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` aggregation type. It serves to adjust the aggregation result by assigning weights and proration to the result based on time intervals. When this field is not provided, the default time interval is assumed to be in `seconds`.
        filters:
          type: array
          items:
            $ref: '#/components/schemas/BillableMetricFilterInput'
    BillableMetricCreateInput:
      type: object
      required:
        - billable_metric
      properties:
        billable_metric:
          $ref: '#/components/schemas/BillableMetricBaseInput'
          required:
            - name
            - code
            - aggregation_type
    BillableMetric:
      type: object
      required:
        - billable_metric
      properties:
        billable_metric:
          $ref: '#/components/schemas/BillableMetricObject'
    BillableMetricEvaluateExpressionInput:
      type: object
      required:
        - expression
        - event
      properties:
        expression:
          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.
            Round is accepting an optional second parameter to specify the number of decimal.
        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
    BillableMetricEvaluateExpressionResult:
      type: object
      required:
        - expression_result
      properties:
        expression_result:
          type: object
          required:
            - value
          properties:
            value:
              anyOf:
                - type: string
                - type: number
              example: 1
              description: Result of evaluating the expression
    BillableMetricUpdateInput:
      type: object
      required:
        - billable_metric
      properties:
        billable_metric:
          $ref: '#/components/schemas/BillableMetricBaseInput'
    FeaturePrivilegeObject:
      type: object
      required:
        - code
        - name
        - value_type
        - config
      properties:
        code:
          type: string
          example: max
          description: Unique code for the privilege.
        name:
          type:
            - string
            - 'null'
          example: Maximum
          description: Display name for the privilege.
        value_type:
          type: string
          enum:
            - integer
            - boolean
            - string
            - select
          example: integer
          description: 'Data type of the privilege value. Default: string'
        config:
          type: object
          properties:
            select_options:
              type: array
              items:
                type: string
              example:
                - google
                - okta
              description: Array of string, required only when value_type is `select`.
    FeatureObject:
      type: object
      required:
        - code
        - name
        - description
        - privileges
        - created_at
      properties:
        code:
          type: string
          example: seats
          description: Unique code used to identify the feature. Max 255 characters.
        name:
          type:
            - string
            - 'null'
          example: Number of seats
          description: Name of the feature. Max 255 characters.
        description:
          type:
            - string
            - 'null'
          example: Number of users of the account
          description: Description of the feature. Max 600 characters.
        privileges:
          type: array
          items:
            $ref: '#/components/schemas/FeaturePrivilegeObject'
          example:
            - code: max
              name: Maximum
              value_type: integer
              config: {}
            - code: max_admins
              name: Max Admins
              value_type: integer
              config: {}
            - code: root
              name: Allow root user
              value_type: boolean
              config: {}
            - code: provider
              name: SSO Provider
              value_type: select
              config:
                select_options:
                  - google
                  - okta
          description: Privileges associated with this feature. Can be empty.
        created_at:
          type: string
          format: date-time
          example: '2025-07-17T12:34:35Z'
          description: Creation date of the feature.
    FeaturesPaginated:
      type: object
      required:
        - features
        - meta
      properties:
        features:
          type: array
          items:
            $ref: '#/components/schemas/FeatureObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    FeatureBaseInput:
      type: object
      properties:
        name:
          type:
            - string
            - 'null'
          example: Number of seats
          description: Name of the feature.
        description:
          type:
            - string
            - 'null'
          example: Number of users of the account
          description: Internal description of the feature.
        privileges:
          type: array
          items:
            type: object
            required:
              - code
            properties:
              code:
                type: string
                example: max
                description: Unique code for the privilege.
              name:
                type:
                  - string
                  - 'null'
                example: Maximum
                description: Display name for the privilege.
              value_type:
                type: string
                enum:
                  - integer
                  - boolean
                  - string
                  - select
                example: integer
                description: 'Data type of the privilege value. Default: string'
              config:
                type: object
                properties:
                  select_options:
                    type: array
                    items:
                      type: string
                    example:
                      - google
                      - okta
                    description: Array of string, required only when value_type is `select`.
          example:
            - code: max
              name: Maximum
              value_type: integer
            - code: max_admins
              name: Max Admins
              value_type: integer
            - code: root
              name: Allow root user
              value_type: boolean
            - code: provider
              name: SSO Provider
              value_type: select
              config:
                select_options:
                  - google
                  - okta
          description: Privileges associated with this feature. Can be empty.
    FeatureCreateInput:
      type: object
      required:
        - feature
      properties:
        feature:
          allOf:
            - $ref: '#/components/schemas/FeatureBaseInput'
            - type: object
              required:
                - code
              properties:
                code:
                  type: string
                  example: seats
                  description: Unique code used to identify the feature.
    Feature:
      type: object
      required:
        - feature
      properties:
        feature:
          $ref: '#/components/schemas/FeatureObject'
    FeatureUpdateInput:
      type: object
      required:
        - feature
      properties:
        feature:
          $ref: '#/components/schemas/FeatureBaseInput'
    CouponObject:
      type: object
      required:
        - lago_id
        - name
        - code
        - expiration
        - coupon_type
        - frequency
        - created_at
        - reusable
        - limited_plans
        - limited_billable_metrics
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the coupon, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        name:
          type: string
          description: The name of the coupon.
          example: Startup Deal
        code:
          type: string
          description: Unique code used to identify the coupon.
          example: startup_deal
        description:
          type:
            - string
            - 'null'
          description: Description of the coupon.
          example: I am a coupon description
        coupon_type:
          type: string
          enum:
            - fixed_amount
            - percentage
          description: |-
            The type of the coupon. It can have two possible values: `fixed_amount` or `percentage`.

            - If set to `fixed_amount`, the coupon represents a fixed amount discount.
            - If set to `percentage`, the coupon represents a percentage-based discount.
          example: fixed_amount
        amount_cents:
          type:
            - integer
            - 'null'
          description: The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type.
          example: 5000
        amount_currency:
          $ref: '#/components/schemas/CurrencyOrNull'
          description: The currency of the coupon. This field is required only for coupon with `fixed_amount` type.
          example: USD
        reusable:
          type: boolean
          description: Indicates whether the coupon can be reused or not. If set to `true`, the coupon is reusable, meaning it can be applied multiple times to the same customer. If set to `false`, the coupon can only be used once and is not reusable. If not specified, this field is set to `true` by default.
          example: true
        limited_plans:
          type: boolean
          description: The coupon is limited to specific plans. The possible values can be `true` or `false`.
          example: true
        plan_codes:
          type: array
          description: An array of plan codes to which the coupon is applicable. By specifying the plan codes in this field, you can restrict the coupon's usage to specific plans only.
          items:
            type: string
          example:
            - startup_plan
        limited_billable_metrics:
          type: boolean
          description: The coupon is limited to specific billable metrics. The possible values can be `true` or `false`.
          example: false
        billable_metric_codes:
          type: array
          description: An array of billable metric codes to which the coupon is applicable. By specifying the billable metric codes in this field, you can restrict the coupon's usage to specific metrics only.
          items:
            type: string
          example: []
        percentage_rate:
          type:
            - string
            - 'null'
          pattern: ^[0-9]+.?[0-9]*$
          description: The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type.
          example: null
        frequency:
          type: string
          description: |-
            The type of frequency for the coupon. It can have three possible values: `once`, `recurring`, or `forever`.

            - If set to `once`, the coupon is applicable only for a single use.
            - If set to `recurring`, the coupon can be used multiple times for recurring billing periods.
            - If set to `forever`, the coupon has unlimited usage and can be applied indefinitely.
          enum:
            - once
            - recurring
            - forever
          example: recurring
        frequency_duration:
          type:
            - integer
            - 'null'
          description: Specifies the number of billing periods to which the coupon applies. This field is required only for coupons with a `recurring` frequency type
          example: 6
        expiration:
          type: string
          description: |-
            Specifies the type of expiration for the coupon. It can have two possible values: `time_limit` or `no_expiration`.

            - If set to `time_limit`, the coupon has an expiration based on a specified time limit.
            - If set to `no_expiration`, the coupon does not have an expiration date and remains valid indefinitely.
          enum:
            - no_expiration
            - time_limit
          example: time_limit
        expiration_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The expiration date and time of the coupon. This field is required only for coupons with `expiration` set to `time_limit`. The expiration date and time should be specified in UTC format according to the ISO 8601 datetime standard. It indicates the exact moment when the coupon will expire and is no longer valid.
          example: '2022-08-08T23:59:59Z'
        created_at:
          type: string
          format: date-time
          description: The date and time when the coupon was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the coupon was initially created.
          example: '2022-04-29T08:59:51Z'
        terminated_at:
          type:
            - string
            - 'null'
          format: date-time
          description: This field indicates if the coupon has been terminated and is no longer usable. If it's not null, it won't be removed for existing customers using it, but it prevents the coupon from being applied in the future.
          example: '2022-08-08T23:59:59Z'
    CouponsPaginated:
      type: object
      required:
        - coupons
        - meta
      properties:
        coupons:
          type: array
          items:
            $ref: '#/components/schemas/CouponObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    CouponBaseInput:
      type: object
      properties:
        name:
          type: string
          description: The name of the coupon.
          example: Startup Deal
        code:
          type: string
          description: Unique code used to identify the coupon.
          example: startup_deal
        description:
          type:
            - string
            - 'null'
          description: Description of the coupon.
          example: I am a coupon description
        coupon_type:
          type: string
          enum:
            - fixed_amount
            - percentage
          description: |-
            The type of the coupon. It can have two possible values: `fixed_amount` or `percentage`.

            - If set to `fixed_amount`, the coupon represents a fixed amount discount.
            - If set to `percentage`, the coupon represents a percentage-based discount.
          example: fixed_amount
        amount_cents:
          type:
            - integer
            - 'null'
          description: The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type.
          example: 5000
        amount_currency:
          $ref: '#/components/schemas/CurrencyOrNull'
          description: The currency of the coupon. This field is required only for coupon with `fixed_amount` type.
          example: USD
        reusable:
          type: boolean
          description: Indicates whether the coupon can be reused or not. If set to `true`, the coupon is reusable, meaning it can be applied multiple times to the same customer. If set to `false`, the coupon can only be used once and is not reusable. If not specified, this field is set to `true` by default.
          example: false
        percentage_rate:
          type:
            - string
            - 'null'
          pattern: ^[0-9]+.?[0-9]*$
          description: The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type.
          example: null
        frequency:
          type: string
          enum:
            - once
            - recurring
            - forever
          description: |-
            The type of frequency for the coupon. It can have three possible values: `once`, `recurring` or `forever`.

            - If set to `once`, the coupon is applicable only for a single use.
            - If set to `recurring`, the coupon can be used multiple times for recurring billing periods.
            - If set to `forever`, the coupon has unlimited usage and can be applied indefinitely.
          example: recurring
        frequency_duration:
          type:
            - integer
            - 'null'
          description: Specifies the number of billing periods to which the coupon applies. This field is required only for coupons with a `recurring` frequency type
          example: 6
        expiration:
          type: string
          enum:
            - no_expiration
            - time_limit
          description: |-
            Specifies the type of expiration for the coupon. It can have two possible values: `time_limit` or `no_expiration`.

            - If set to `time_limit`, the coupon has an expiration based on a specified time limit.
            - If set to `no_expiration`, the coupon does not have an expiration date and remains valid indefinitely.
          example: time_limit
        expiration_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The expiration date and time of the coupon. This field is required only for coupons with `expiration` set to `time_limit`. The expiration date and time should be specified in UTC format according to the ISO 8601 datetime standard. It indicates the exact moment when the coupon will expire and is no longer valid.
          example: '2022-08-08T23:59:59Z'
        applies_to:
          type:
            - object
            - 'null'
          description: Set coupon limitations to plans or specific metrics.
          properties:
            plan_codes:
              type:
                - array
                - 'null'
              items:
                type: string
              description: An array of plan codes to which the coupon is applicable. By specifying the plan codes in this field, you can restrict the coupon's usage to specific plans only.
              example:
                - startup_plan
            billable_metric_codes:
              type:
                - array
                - 'null'
              items:
                type: string
              description: An array of billable metric codes to which the coupon is applicable. By specifying the billable metric codes in this field, you can restrict the coupon's usage to specific metrics only.
              example: []
    CouponCreateInput:
      type: object
      required:
        - coupon
      properties:
        coupon:
          $ref: '#/components/schemas/CouponBaseInput'
          required:
            - name
            - code
            - coupon_type
            - frequency
            - expiration
    Coupon:
      type: object
      required:
        - coupon
      properties:
        coupon:
          $ref: '#/components/schemas/CouponObject'
    CouponUpdateInput:
      type: object
      required:
        - coupon
      properties:
        coupon:
          $ref: '#/components/schemas/CouponBaseInput'
    FeeAmountDetails:
      type: object
      properties:
        plan_amount_cents:
          type: integer
          description: The base cost of the plan, excluding any applicable taxes, that is billed on a recurring basis. This value is defined at 0 if your plan is a pay-as-you-go plan.
          example: 10000
        graduated_ranges:
          type: array
          description: Graduated ranges, used for a `graduated` charge model.
          items:
            type: object
            required:
              - units
              - from_value
              - to_value
              - flat_unit_amount
              - per_unit_amount
              - per_unit_total_amount
              - total_with_flat_amount
            properties:
              units:
                type: string
                pattern: ^[0-9]+.?[0-9]*$
                example: '10.0'
                description: Total units received in Lago.
              from_value:
                type: integer
                description: Lower value of a tier. It is either 0 or the previous range's `to_value + 1`.
                example: 0
              to_value:
                type:
                  - integer
                  - 'null'
                description: |-
                  Highest value of a tier.
                  - This value is higher than the from_value of the same tier.
                  - This value is null for the last tier.
                example: 10
              flat_unit_amount:
                type: string
                description: Flat unit amount within a specified tier.
                example: '1.0'
              per_unit_amount:
                type: string
                description: Amount per unit within a specified tier.
                example: '1.0'
              per_unit_total_amount:
                type: string
                description: Total amount of received units to be charged within a specified tier.
                example: '10.0'
              total_with_flat_amount:
                type: string
                description: Total amount to be charged for a specific tier, taking into account the flat_unit_amount and the per_unit_total_amount.
                example: '11.0'
        graduated_percentage_ranges:
          type: array
          description: Graduated percentage ranges, used for a `graduated_percentage` charge model.
          items:
            type: object
            required:
              - units
              - from_value
              - to_value
              - flat_unit_amount
              - rate
              - per_unit_total_amount
              - total_with_flat_amount
            properties:
              units:
                type: string
                pattern: ^[0-9]+.?[0-9]*$
                example: '10.0'
                description: Total units received in Lago.
              from_value:
                type: integer
                description: Lower value of a tier. It is either 0 or the previous range's `to_value + 1`.
                example: 0
              to_value:
                type:
                  - integer
                  - 'null'
                description: |-
                  Highest value of a tier.
                  - This value is higher than the from_value of the same tier.
                  - This value is null for the last tier.
                example: 10
              flat_unit_amount:
                type: string
                description: Flat unit amount within a specified tier.
                example: '1.0'
              rate:
                type: string
                format: ^[0-9]+.?[0-9]*$
                description: Percentage rate applied within a specified tier.
                example: '1.0'
              per_unit_total_amount:
                type: string
                description: Total amount of received units to be charged within a specified tier.
                example: '10.0'
              total_with_flat_amount:
                type: string
                description: Total amount to be charged for a specific tier, taking into account the flat_unit_amount and the per_unit_total_amount.
                example: '11.0'
        free_units:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          example: '10.0'
          description: The quantity of units that are provided free of charge for each billing period in a `package` charge model.
        paid_units:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          example: '40.0'
          description: The quantity of units that are not provided free of charge for each billing period in a `package` charge model.
        per_package_size:
          type: integer
          description: The quantity of units included, defined for Package or Percentage charge model.
          example: 1000
        per_package_unit_amount:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: Total amount to charge for received paid_units, defined for Package or Percentage charge model.
          example: '0.5'
        per_unit_total_amount:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: Total amount of received units to be charged for the Volume or Percentage charge model.
          example: '10.0'
        units:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          example: '20.0'
          description: The total units received in Lago for the Percentage charge model.
        free_events:
          type: integer
          example: 10
          description: Total number of free events allowed for the Percentage charge model.
        rate:
          type: string
          format: ^[0-9]+.?[0-9]*$
          description: Percentage rate applied for the Percentage charge model.
          example: '1.0'
        paid_events:
          type: integer
          example: 20
          description: Total number of paid events for the Percentage charge model.
        fixed_fee_unit_amount:
          type: string
          description: Fixed fee unit price per received paid_event for the Percentage charge model.
          example: '1.0'
        fixed_fee_total_amount:
          type: string
          description: Total amount to charge for received paid_events for the Percentage charge model.
          example: '20.0'
        min_max_adjustment_total_amount:
          type: string
          description: Total adjustment amount linked to minimum and maximum spending per transaction for the Percentage charge model.
          example: '20.0'
        per_unit_amount:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: The flat amount for a whole tier, excluding tax, for a `volume` charge model.
          example: '0.5'
        flat_unit_amount:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: The unit price, excluding tax, for a specific tier of a `volume` charge model.
          example: '10.0'
    BaseAppliedTax:
      type: object
      required:
        - lago_id
        - lago_tax_id
        - tax_name
        - tax_code
        - tax_rate
        - tax_description
        - amount_cents
        - amount_currency
        - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the applied tax, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_tax_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Unique identifier of the tax, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        tax_name:
          type: string
          description: Name of the tax.
          example: TVA
        tax_code:
          type: string
          description: Unique code used to identify the tax associated with the API request.
          example: french_standard_vat
        tax_rate:
          type: number
          description: The percentage rate of the tax
          example: 20
        tax_description:
          type:
            - string
            - 'null'
          description: Internal description of the tax
          example: French standard VAT
        amount_cents:
          type: integer
          description: Amount of the tax
          example: 2000
        amount_currency:
          $ref: '#/components/schemas/Currency'
          description: Currency of the tax
          example: USD
        created_at:
          type: string
          format: date-time
          description: The date and time when the applied tax was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the applied tax was initially created.
          example: '2022-09-14T16:35:31Z'
    FeeAppliedTaxObject:
      allOf:
        - $ref: '#/components/schemas/BaseAppliedTax'
      type: object
      properties:
        lago_fee_id:
          type: string
          format: uuid
          description: Unique identifier of the fee, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
    PricingUnitDetailsObject:
      type: object
      required:
        - lago_pricing_unit_id
        - pricing_unit_code
        - short_name
        - amount_cents
        - precise_amount_cents
        - unit_amount_cents
        - precise_unit_amount
        - conversion_rate
      properties:
        lago_pricing_unit_id:
          type: string
          format: uuid
          description: Unique identifier of the pricing unit, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        pricing_unit_code:
          type: string
          description: The code of the pricing unit.
          example: credits
        short_name:
          type: string
          description: The short name of the pricing unit. Will be used as currency name in the UI and PDFs.
          example: CR
        amount_cents:
          type: integer
          description: The amount in cents in the pricing unit.
          example: 200
        precise_amount_cents:
          type: string
          description: The precise amount in cents in the pricing unit.
          example: '200.0'
        unit_amount_cents:
          type: integer
          description: The unit amount in cents in the pricing unit.
          example: 100
        precise_unit_amount:
          type: string
          description: The precise unit amount in the pricing unit.
          example: '100.0'
        conversion_rate:
          type: string
          description: The conversion rate from pricing units to the plan's currency.
          example: '0.5'
    PresentationBreakdownsObject:
      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.
    FeeObject:
      type: object
      required:
        - item
        - amount_cents
        - amount_currency
        - taxes_amount_cents
        - taxes_rate
        - total_amount_cents
        - total_amount_currency
        - pay_in_advance
        - invoiceable
        - units
        - total_aggregated_units
        - precise_unit_amount
        - sub_total_excluding_taxes_amount_cents
        - sub_total_excluding_taxes_precise_amount_cents
        - payment_status
      properties:
        lago_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Unique identifier assigned to the fee within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the fee's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_charge_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Unique identifier assigned to the charge that the fee belongs to
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_charge_filter_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Unique identifier assigned to the charge filter that the fee belongs to
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_fixed_charge_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Unique identifier assigned to the fixed charge that the fee belongs to
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_invoice_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Unique identifier assigned to the invoice that the fee belongs to
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_true_up_fee_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Unique identifier assigned to the true-up fee when a minimum has been set to the charge. This identifier helps to distinguish and manage the true-up fee associated with the charge, which may be applicable when a minimum threshold or limit is set for the charge amount.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_true_up_parent_fee_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Unique identifier assigned to the parent fee on which the true-up fee is assigned. This identifier establishes the relationship between the parent fee and the associated true-up fee.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_subscription_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Unique identifier assigned to the subscription, created by Lago. This field is specifically displayed when the fee type is charge or subscription.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_customer_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Unique identifier assigned to the customer, created by Lago. This field is specifically displayed when the fee type is charge or subscription.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_customer_id:
          type:
            - string
            - 'null'
          description: Unique identifier assigned to the customer in your application. This field is specifically displayed when the fee type is charge or subscription.
          example: external_id
        external_subscription_id:
          type:
            - string
            - 'null'
          description: Unique identifier assigned to the subscription in your application. This field is specifically displayed when the fee type is charge or subscription.
          example: external_id
        amount_cents:
          type: integer
          description: The cost of this specific fee, excluding any applicable taxes.
          example: 100
        precise_amount:
          type: string
          description: The cost of this specific fee, excluding any applicable taxes, with precision.
          example: '1.0001'
        precise_total_amount:
          type: string
          description: The cost of this specific fee, including any applicable taxes, with precision.
          example: '1.0212'
        amount_currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of this specific fee. It indicates the monetary unit in which the fee's cost is expressed.
          example: EUR
        taxes_amount_cents:
          type: integer
          description: The cost of the tax associated with this specific fee.
          example: 20
        taxes_precise_amount:
          type: string
          description: The cost of the tax associated with this specific fee, with precision.
          example: '0.20123'
        taxes_rate:
          type: number
          description: The tax rate associated with this specific fee.
          example: 20
        units:
          type: string
          description: The number of units used to charge the customer. This field indicates the quantity or count of units consumed or utilized in the context of the charge. It helps in determining the basis for calculating the fee or cost associated with the usage of the service or product provided to the customer.
          example: '0.32'
        precise_unit_amount:
          type: string
          description: The unit amount of the fee per unit, with precision.
          example: '312.5'
        total_aggregated_units:
          type: string
          description: The total number of units that have been aggregated for this specific fee.
          example: '0.32'
        total_amount_cents:
          type: integer
          description: The cost of this specific fee, including any applicable taxes.
          example: 120
        total_amount_currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of this specific fee, including any applicable taxes.
          example: EUR
        events_count:
          type:
            - integer
            - 'null'
          description: The number of events that have been sent and used to charge the customer. This field indicates the count or quantity of events that have been processed and considered in the charging process.
          example: 23
        pay_in_advance:
          type: boolean
          description: Flag that indicates whether the fee was paid in advance. It serves as a boolean value, where `true` represents that the fee was paid in advance (straightaway), and `false` indicates that the fee was not paid in arrears (at the end of the period).
          example: true
        invoiceable:
          type: boolean
          description: Flag that indicates whether the fee was included on the invoice. It serves as a boolean value, where `true` represents that the fee was included on the invoice, and `false` indicates that the fee was not included on the invoice.
          example: true
        from_date:
          type:
            - string
            - 'null'
          format: date-time
          description: The beginning date of the period that the fee covers. It is applicable only to `subscription`, `charge`, `fixed_charge` and `commitment` fees. This field indicates the start date of the billing period or subscription period associated with the fee.
          example: '2022-04-29T08:59:51Z'
        to_date:
          type:
            - string
            - 'null'
          format: date-time
          description: The ending date of the period that the fee covers. It is applicable only to `subscription`, `charge`, `fixed_charge` and `commitment` fees. This field indicates the end date of the billing period or subscription period associated with the fee.
          example: '2022-05-29T08:59:51Z'
        payment_status:
          type: string
          enum:
            - pending
            - succeeded
            - failed
            - refunded
          description: Indicates the payment status of the fee. It represents the current status of the payment associated with the fee. The possible values for this field are `pending`, `succeeded`, `failed` and `refunded`.
          example: pending
        created_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time when the fee was created. It is provided in Coordinated Universal Time (UTC) format.
          example: '2022-08-24T14:58:59Z'
        succeeded_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time when the payment for the fee was successfully processed. It is provided in Coordinated Universal Time (UTC) format.
          example: '2022-08-24T14:58:59Z'
        failed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time when the payment for the fee failed to process. It is provided in Coordinated Universal Time (UTC) format.
          example: '2022-08-24T14:58:59Z'
        refunded_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time when the payment for the fee was refunded. It is provided in Coordinated Universal Time (UTC) format
          example: '2022-08-24T14:58:59Z'
        event_transaction_id:
          type:
            - string
            - 'null'
          description: Unique identifier assigned to the transaction. This field is specifically displayed when the fee type is `charge` and the payment for the fee is made in advance (`pay_in_advance` is set to `true`).
          example: transaction_1234567890
        description:
          type:
            - string
            - 'null'
          description: The description of the fee.
          example: Fee description
        precise_coupons_amount_cents:
          type: string
          description: The coupon amount applied to the fee, with precision.
          example: '0.0'
        sub_total_excluding_taxes_amount_cents:
          type: integer
          description: The sub total of the fee excluding taxes, in cents.
          example: 100
        sub_total_excluding_taxes_precise_amount_cents:
          type: string
          description: The sub total of the fee excluding taxes, with precision.
          example: '100.0'
        amount_details:
          $ref: '#/components/schemas/FeeAmountDetails'
          description: List of all unit amount details for calculating the fee.
        self_billed:
          type: boolean
          example: false
          description: Indicates if the fee belongs to self-billed invoice. Self-billing is a process where an organization creates the invoice on behalf of the partner.
        item:
          type: object
          description: Item attached to the fee
          required:
            - type
            - code
            - name
            - lago_item_id
            - item_type
          properties:
            type:
              type: string
              enum:
                - charge
                - fixed_charge
                - add_on
                - subscription
                - credit
                - commitment
              description: The fee type. Possible values are `add-on`, `charge`, `fixed_charge`, `credit`, `subscription` or `commitment`.
              example: subscription
            code:
              type: string
              description: The code of the fee item. It can be the code of the `add-on`, the code of the `charge`, the code of the `fixed_charge`, the code of the `credit` or the code of the `subscription`.
              example: startup
            name:
              type: string
              description: |
                The name of the fee item. The value depends on the type of the fee item:

                - If the fee item is a `charge`, it is the billable metric name.
                - If the fee item is a `add-on`, it is the add-on name.
                - If the fee item is a `credit`, it is the wallet transaction name if set, or `"credit"` if not.
                - If the fee item is a `fixed_charge`, it is the fixed charge add-on name.
                - For all the other fee items, it is the subscription plan name.
              example: Startup
            description:
              type:
                - string
                - 'null'
              description: |
                The description of the fee item. The value depends on the type of the fee item:

                - If the fee item is a `charge`, it is the billable metric description.
                - If the fee item is a `add-on`, it is the add-on description.
                - If the fee item is a `credit`, it is always `"credit"`.
                - If the fee item is a `fixed_charge`, it is the fixed charge add-on description.
                - For all the other fee items, it is the subscription plan description.
              example: Startup
            invoice_display_name:
              type: string
              description: |
                Specifies the name that will be displayed on an invoice. If no value is set for this field, we'll fallback to a value that depends on the type of the fee items:

                - If the fee item is a `charge`, we'll fallback to the `invoice_display_name` of the `charge` or the billable metric name if no `invoice_display_name` is set.
                - If the fee item is a `add-on`, we'll fallback to the `invoice_name` of the `add-on` or the `name` of the `add-on`.
                - If the fee item is a `credit`, we'll fallback to the wallet transaction name if set, or `credit` if not.
                - If the fee item is a `fixed_charge`, we'll fallback to the `invoice_display_name` of the `fixed_charge` or the `invoice_name` of the `fixed_charge_add_on` if no `invoice_display_name` is set.
                - For all the other fee items, we'll fallback to the `invoice_display_name` of the subscription plan.
              example: Setup Fee (SF1)
            filter_invoice_display_name:
              type:
                - string
                - 'null'
              description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the actual charge filter values will be used as the default display name.
              example: AWS eu-east-1
            filters:
              type:
                - object
                - 'null'
              description: Key value list of event properties
              additionalProperties:
                type: array
                items:
                  type: string
            lago_item_id:
              type: string
              example: 1a901a90-1a90-1a90-1a90-1a901a901a90
              description: Unique identifier of the fee item, created by Lago. It can be the identifier of the `add-on`, the `charge`, the `credit`, the `subscription` or the `commitment`.
              format: uuid
            item_type:
              type: string
              enum:
                - AddOn
                - BillableMetric
                - Subscription
                - WalletTransaction
              description: The type of the fee item. Possible values are `AddOn`, `BillableMetric`, `WalletTransaction`, `Subscription`.
              example: Subscription
            grouped_by:
              type: object
              description: Key value list of event properties aggregated by the charge model
              additionalProperties:
                type: string
        applied_taxes:
          type: array
          description: List of fee applied taxes
          items:
            $ref: '#/components/schemas/FeeAppliedTaxObject'
        pricing_unit_details:
          type:
            - object
            - 'null'
          description: Details about the pricing unit used and amounts for this fee.
          $ref: '#/components/schemas/PricingUnitDetailsObject'
        presentation_breakdowns:
          $ref: '#/components/schemas/PresentationBreakdownsObject'
    CreditNoteItemObject:
      type: object
      required:
        - lago_id
        - amount_cents
        - amount_currency
        - fee
      properties:
        lago_id:
          type: string
          format: uuid
          description: The credit note's item unique identifier, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        amount_cents:
          type: integer
          description: The credit note's item amount, expressed in cents.
          example: 100
        amount_currency:
          $ref: '#/components/schemas/Currency'
          description: The credit note's item currency.
          example: EUR
        fee:
          $ref: '#/components/schemas/FeeObject'
          description: The fee object related to the credit note item.
    CreditNoteAppliedTaxObject:
      allOf:
        - $ref: '#/components/schemas/BaseAppliedTax'
      type: object
      properties:
        lago_credit_note_id:
          type: string
          format: uuid
          description: Unique identifier of the credit note, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        base_amount_cents:
          type: integer
          example: 100
    CountryOrNull:
      type:
        - string
        - 'null'
      example: US
      enum:
        - null
        - AD
        - AE
        - AF
        - AG
        - AI
        - AL
        - AM
        - AO
        - AQ
        - AR
        - AS
        - AT
        - AU
        - AW
        - AX
        - AZ
        - BA
        - BB
        - BD
        - BE
        - BF
        - BG
        - BH
        - BI
        - BJ
        - BL
        - BM
        - BN
        - BO
        - BQ
        - BR
        - BS
        - BT
        - BV
        - BW
        - BY
        - BZ
        - CA
        - CC
        - CD
        - CF
        - CG
        - CH
        - CI
        - CK
        - CL
        - CM
        - CN
        - CO
        - CR
        - CU
        - CV
        - CW
        - CX
        - CY
        - CZ
        - DE
        - DJ
        - DK
        - DM
        - DO
        - DZ
        - EC
        - EE
        - EG
        - EH
        - ER
        - ES
        - ET
        - FI
        - FJ
        - FK
        - FM
        - FO
        - FR
        - GA
        - GB
        - GD
        - GE
        - GF
        - GG
        - GH
        - GI
        - GL
        - GM
        - GN
        - GP
        - GQ
        - GR
        - GS
        - GT
        - GU
        - GW
        - GY
        - HK
        - HM
        - HN
        - HR
        - HT
        - HU
        - ID
        - IE
        - IL
        - IM
        - IN
        - IO
        - IQ
        - IR
        - IS
        - IT
        - JE
        - JM
        - JO
        - JP
        - KE
        - KG
        - KH
        - KI
        - KM
        - KN
        - KP
        - KR
        - KW
        - KY
        - KZ
        - LA
        - LB
        - LC
        - LI
        - LK
        - LR
        - LS
        - LT
        - LU
        - LV
        - LY
        - MA
        - MC
        - MD
        - ME
        - MF
        - MG
        - MH
        - MK
        - ML
        - MM
        - MN
        - MO
        - MP
        - MQ
        - MR
        - MS
        - MT
        - MU
        - MV
        - MW
        - MX
        - MY
        - MZ
        - NA
        - NC
        - NE
        - NF
        - NG
        - NI
        - NL
        - 'NO'
        - NP
        - NR
        - NU
        - NZ
        - OM
        - PA
        - PE
        - PF
        - PG
        - PH
        - PK
        - PL
        - PM
        - PN
        - PR
        - PS
        - PT
        - PW
        - PY
        - QA
        - RE
        - RO
        - RS
        - RU
        - RW
        - SA
        - SB
        - SC
        - SD
        - SE
        - SG
        - SH
        - SI
        - SJ
        - SK
        - SL
        - SM
        - SN
        - SO
        - SR
        - SS
        - ST
        - SV
        - SX
        - SY
        - SZ
        - TC
        - TD
        - TF
        - TG
        - TH
        - TJ
        - TK
        - TL
        - TM
        - TN
        - TO
        - TR
        - TT
        - TV
        - TW
        - TZ
        - UA
        - UG
        - UM
        - US
        - UY
        - UZ
        - VA
        - VC
        - VE
        - VG
        - VI
        - VN
        - VU
        - WF
        - WS
        - YE
        - YT
        - ZA
        - ZM
        - ZW
    TimezoneOrNull:
      type:
        - string
        - 'null'
      example: America/Los_Angeles
      enum:
        - null
        - UTC
        - Africa/Algiers
        - Africa/Cairo
        - Africa/Casablanca
        - Africa/Harare
        - Africa/Johannesburg
        - Africa/Monrovia
        - Africa/Nairobi
        - America/Argentina/Buenos_Aires
        - America/Bogota
        - America/Caracas
        - America/Chicago
        - America/Chihuahua
        - America/Denver
        - America/Godthab
        - America/Guatemala
        - America/Guyana
        - America/Halifax
        - America/Indiana/Indianapolis
        - America/Juneau
        - America/La_Paz
        - America/Lima
        - America/Los_Angeles
        - America/Mazatlan
        - America/Mexico_City
        - America/Monterrey
        - America/Montevideo
        - America/New_York
        - America/Phoenix
        - America/Puerto_Rico
        - America/Regina
        - America/Santiago
        - America/Sao_Paulo
        - America/St_Johns
        - America/Tijuana
        - Asia/Almaty
        - Asia/Baghdad
        - Asia/Baku
        - Asia/Bangkok
        - Asia/Chongqing
        - Asia/Colombo
        - Asia/Dhaka
        - Asia/Hong_Kong
        - Asia/Irkutsk
        - Asia/Jakarta
        - Asia/Jerusalem
        - Asia/Kabul
        - Asia/Kamchatka
        - Asia/Karachi
        - Asia/Kathmandu
        - Asia/Kolkata
        - Asia/Krasnoyarsk
        - Asia/Kuala_Lumpur
        - Asia/Kuwait
        - Asia/Magadan
        - Asia/Muscat
        - Asia/Novosibirsk
        - Asia/Rangoon
        - Asia/Riyadh
        - Asia/Seoul
        - Asia/Shanghai
        - Asia/Singapore
        - Asia/Srednekolymsk
        - Asia/Taipei
        - Asia/Tashkent
        - Asia/Tbilisi
        - Asia/Tehran
        - Asia/Tokyo
        - Asia/Ulaanbaatar
        - Asia/Urumqi
        - Asia/Vladivostok
        - Asia/Yakutsk
        - Asia/Yekaterinburg
        - Asia/Yerevan
        - Atlantic/Azores
        - Atlantic/Cape_Verde
        - Atlantic/South_Georgia
        - Australia/Adelaide
        - Australia/Brisbane
        - Australia/Darwin
        - Australia/Hobart
        - Australia/Melbourne
        - Australia/Perth
        - Australia/Sydney
        - Europe/Amsterdam
        - Europe/Athens
        - Europe/Belgrade
        - Europe/Berlin
        - Europe/Bratislava
        - Europe/Brussels
        - Europe/Bucharest
        - Europe/Budapest
        - Europe/Copenhagen
        - Europe/Dublin
        - Europe/Helsinki
        - Europe/Istanbul
        - Europe/Kaliningrad
        - Europe/Kiev
        - Europe/Lisbon
        - Europe/Ljubljana
        - Europe/London
        - Europe/Madrid
        - Europe/Minsk
        - Europe/Moscow
        - Europe/Paris
        - Europe/Prague
        - Europe/Riga
        - Europe/Rome
        - Europe/Samara
        - Europe/Sarajevo
        - Europe/Skopje
        - Europe/Sofia
        - Europe/Stockholm
        - Europe/Tallinn
        - Europe/Vienna
        - Europe/Vilnius
        - Europe/Volgograd
        - Europe/Warsaw
        - Europe/Zagreb
        - Europe/Zurich
        - GMT+12
        - Pacific/Apia
        - Pacific/Auckland
        - Pacific/Chatham
        - Pacific/Fakaofo
        - Pacific/Fiji
        - Pacific/Guadalcanal
        - Pacific/Guam
        - Pacific/Honolulu
        - Pacific/Majuro
        - Pacific/Midway
        - Pacific/Noumea
        - Pacific/Pago_Pago
        - Pacific/Port_Moresby
        - Pacific/Tongatapu
    CustomerBillingConfiguration:
      type: object
      description: Configuration specific to the payment provider, utilized for billing the customer. This object contains settings and parameters necessary for processing payments and invoicing the customer.
      properties:
        invoice_grace_period:
          type: integer
          example: 3
          description: The grace period, expressed in days, for the invoice. This period refers to the additional time granted to the customer beyond the invoice due date to adjust usage and line items
        subscription_invoice_issuing_date_anchor:
          type:
            - string
            - 'null'
          example: next_period_start
          description: Defines whether the issuing date follows the current billing period's end date or the next period starting date.
          enum:
            - current_period_end
            - next_period_start
            - null
          default: null
        subscription_invoice_issuing_date_adjustment:
          type:
            - string
            - 'null'
          example: keep_anchor
          description: The logic applied on top of the subscription_invoice_issuing_date_anchor rule. You can opt to use the invoice finalization date, that includes any configured grace period.
          enum:
            - align_with_finalization_date
            - keep_anchor
            - null
          default: null
        payment_provider:
          type: string
          example: stripe
          description: |-
            The payment provider utilized to initiate payments for invoices issued by Lago.
            Accepted values: `stripe`, `adyen`, `gocardless` or null. This field is required if you intend to assign a `provider_customer_id`.
          enum:
            - stripe
            - adyen
            - gocardless
        payment_provider_code:
          type: string
          example: stripe-eu-1
          description: Unique code used to identify a payment provider connection.
        provider_customer_id:
          type: string
          example: cus_12345
          description: The customer ID within the payment provider's system. If this field is not provided, Lago has the option to create a new customer record within the payment provider's system on behalf of the customer
        sync:
          type: boolean
          example: true
          description: Set this field to `true` if you want to create the customer in the payment provider synchronously with the customer creation process in Lago. This option is applicable only when the `provider_customer_id` is `null` and the customer is automatically created in the payment provider through Lago. By default, the value is set to `false`
        sync_with_provider:
          type: boolean
          example: true
          description: Set this field to `true` if you want to create a customer record in the payment provider's system. This option is applicable only when the `provider_customer_id` is null and the `sync_with_provider` field is set to `true`. By default, the value is set to `false`
        document_locale:
          type: string
          example: fr
          description: The document locale, specified in the ISO 639-1 format. This field represents the language or locale used for the documents issued by Lago
        provider_payment_methods:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Specifies the available payment methods that can be used for this customer when `payment_provider` is set to `stripe`. The `provider_payment_methods` field is an array that allows multiple payment options to be defined. If this field is not explicitly set, the payment methods will be set to `card`. For now, possible values are `card`, `sepa_debit`, `us_bank_account`, `bacs_debit`, `boleto`, `link`, `crypto` and `customer_balance`. Note that when `link` is selected, `card` should also be provided in the array. When `customer_balance` is selected, no other payment can be selected.
          example:
            - card
            - sepa_debit
            - us_bank_account
            - bacs_debit
            - link
            - boleto
            - crypto
            - customer_balance
    Address:
      type: object
      description: Configuration specific to the payment provider, utilized for billing the customer. This object contains settings and parameters necessary for processing payments and invoicing the customer.
      properties:
        address_line1:
          type:
            - string
            - 'null'
          example: 5230 Penfield Ave
          description: The first line of the billing address
        address_line2:
          type:
            - string
            - 'null'
          example: null
          description: The second line of the billing address
        city:
          type:
            - string
            - 'null'
          example: Woodland Hills
          description: The city of the customer's billing address
        country:
          $ref: '#/components/schemas/CountryOrNull'
          description: Country code of the customer's billing address. Format must be ISO 3166 (alpha-2)
          example: US
        state:
          type:
            - string
            - 'null'
          example: CA
          description: The state of the customer's billing address
        zipcode:
          type:
            - string
            - 'null'
          example: '91364'
          description: The zipcode of the customer's billing address
    CustomerMetadata:
      type: object
      description: Set of key-value pairs that you can attach to a customer. This can be useful for storing additional information about the customer in a structured format
      required:
        - lago_id
        - key
        - value
        - display_in_invoice
        - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: A unique identifier for the customer metadata object in the Lago application. Can be used to update a key-value pair
        key:
          type: string
          example: Purchase Order
          description: The metadata object key
        value:
          type: string
          example: '123456789'
          description: The metadata object value
        display_in_invoice:
          type: boolean
          example: true
          description: Determines whether the item or information should be displayed in the invoice. If set to true, the item or information will be included and visible in the generated invoice. If set to false, the item or information will be excluded and not displayed in the invoice.
        created_at:
          type: string
          format: date-time
          example: '2022-04-29T08:59:51Z'
          description: The date of the metadata object creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). The creation_date provides a standardized and internationally recognized timestamp for when the metadata object was created
    CustomerBaseObject:
      type: object
      required:
        - lago_id
        - sequential_id
        - slug
        - external_id
        - applicable_timezone
        - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer's record within the Lago system
        sequential_id:
          type: integer
          example: 1
          description: The unique identifier assigned to the customer within the organization's scope. This identifier is used to track and reference the customer's order of creation within the organization's system. It ensures that each customer has a distinct `sequential_id`` associated with them, allowing for easy identification and sorting based on the order of creation
        slug:
          type: string
          example: LAG-1234-001
          description: A concise and unique identifier for the customer, formed by combining the Organization's `name`, `id`, and customer's `sequential_id`
        external_id:
          type: string
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
          description: The customer external unique identifier (provided by your own application)
        billing_entity_code:
          type: string
          example: acme_corp
          description: The unique code of the billing entity associated with the customer.
        address_line1:
          type:
            - string
            - 'null'
          example: 5230 Penfield Ave
          description: The first line of the billing address
        address_line2:
          type:
            - string
            - 'null'
          example: null
          description: The second line of the billing address
        applicable_timezone:
          $ref: '#/components/schemas/Timezone'
          description: The customer's applicable timezone, used for billing purposes in their local time.
        city:
          type:
            - string
            - 'null'
          example: Woodland Hills
          description: The city of the customer's billing address
        country:
          $ref: '#/components/schemas/CountryOrNull'
          description: Country code of the customer's billing address. Format must be ISO 3166 (alpha-2)
          example: US
        currency:
          $ref: '#/components/schemas/CurrencyOrNull'
          example: USD
          description: Currency of the customer. Format must be ISO 4217
        email:
          type:
            - string
            - 'null'
          format: email
          example: dinesh@piedpiper.test
          description: The email of the customer
        legal_name:
          type:
            - string
            - 'null'
          example: Coleman-Blair
          description: The legal company name of the customer
        legal_number:
          type:
            - string
            - 'null'
          example: 49-008-2965
          description: The legal company number of the customer
        logo_url:
          type:
            - string
            - 'null'
          example: http://hooli.com/logo.png
          description: The logo URL of the customer
        name:
          type:
            - string
            - 'null'
          example: Gavin Belson
          description: The full name of the customer
        firstname:
          type:
            - string
            - 'null'
          example: Gavin
          description: First name of the customer
        lastname:
          type:
            - string
            - 'null'
          example: Belson
          description: Last name of the customer
        account_type:
          type: string
          enum:
            - customer
            - partner
          example: customer
          description: |-
            The type of the account. It can have one of the following values:
            - `customer`: the account is a customer.
            - `partner`: the account is a partner.
        customer_type:
          type:
            - string
            - 'null'
          enum:
            - company
            - individual
            - null
          description: |-
            The type of the customer. It can have one of the following values:
            - `company`: the customer is a company.
            - `individual`: the customer is an individual.
        phone:
          type:
            - string
            - 'null'
          example: 1-171-883-3711 x245
          description: The phone number of the customer
        state:
          type:
            - string
            - 'null'
          example: CA
          description: The state of the customer's billing address
        tax_identification_number:
          type:
            - string
            - 'null'
          example: EU123456789
          description: The tax identification number of the customer
        timezone:
          $ref: '#/components/schemas/TimezoneOrNull'
          description: The customer's timezone, used for billing purposes in their local time. Overrides the organization's timezone
        url:
          type:
            - string
            - 'null'
          example: http://hooli.com
          description: The custom website URL of the customer
        zipcode:
          type:
            - string
            - 'null'
          example: '91364'
          description: The zipcode of the customer's billing address
        net_payment_term:
          type:
            - integer
            - 'null'
          example: 30
          description: The net payment term, expressed in days, specifies the duration within which a customer is expected to remit payment after the invoice is finalized.
        created_at:
          type: string
          format: date-time
          example: '2022-04-29T08:59:51Z'
          description: The date of the customer creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). The creation_date provides a standardized and internationally recognized timestamp for when the customer object was created
        updated_at:
          type: string
          format: date-time
          example: '2022-04-29T08:59:51Z'
          description: The date of the customer update, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). The update_date provides a standardized and internationally recognized timestamp for when the customer object was updated
        finalize_zero_amount_invoice:
          type: string
          enum:
            - inherit
            - skip
            - finalize
          example: inherit
          description: |-
            Specifies how invoices with a zero total amount should be handled:
            - `inherit`: (Default) Follows the organization-level configuration.
            - `finalize`: Invoices are issued and finalized even if the total amount is zero.
            - `skip`: Invoices with a total amount of zero are not finalized.
        skip_invoice_custom_sections:
          type: boolean
          example: false
          description: Set to true to exclude all invoice custom sections from PDF generation for this customer only.
        billing_configuration:
          $ref: '#/components/schemas/CustomerBillingConfiguration'
        shipping_address:
          $ref: '#/components/schemas/Address'
        metadata:
          type: array
          items:
            $ref: '#/components/schemas/CustomerMetadata'
    MetadataObject:
      type:
        - object
        - 'null'
      description: |-
        Custom metadata stored as key-value pairs.
        Keys are strings (max 100 characters), values can be strings (max 255 characters) or null.
      additionalProperties:
        type:
          - string
          - 'null'
      example:
        external_id: ext-123
        synced_at: '2024-01-15'
        source: null
    CreditNoteErrorDetailsObject:
      type: object
      required:
        - lago_id
        - error_code
        - details
      properties:
        lago_id:
          type: string
          format: uuid
          description: The credit note error details unique identifier, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        error_code:
          type: string
          enum:
            - not_provided
            - tax_error
            - tax_voiding_error
            - invoice_generation_error
          description: The type of the error.
          example: tax_error
        details:
          type: object
          description: The details of the error.
    CreditNoteObject:
      type: object
      required:
        - lago_id
        - sequential_id
        - billing_entity_code
        - number
        - lago_invoice_id
        - invoice_number
        - issuing_date
        - reason
        - currency
        - total_amount_cents
        - credit_amount_cents
        - refund_amount_cents
        - offset_amount_cents
        - balance_amount_cents
        - taxes_amount_cents
        - taxes_rate
        - sub_total_excluding_taxes_amount_cents
        - coupons_adjustment_amount_cents
        - created_at
        - updated_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: The credit note unique identifier, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        billing_entity_code:
          type: string
          example: acme_corp
          description: The unique code of the billing entity associated with the credit note.
        sequential_id:
          type: integer
          description: The sequential identifier of the credit note, specifically scoped on the associated invoice. It provides a unique numerical identifier for the credit note within the context of the invoice.
          example: 2
        number:
          type: string
          description: The credit note unique number.
          example: LAG-1234-CN2
        lago_invoice_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the invoice that the credit note belongs to
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        invoice_number:
          type: string
          description: The invoice unique number, related to the credit note.
          example: LAG-1234
        issuing_date:
          type: string
          format: date
          description: The date of creation of the credit note. It follows the ISO 8601 date format and provides the specific date when the credit note was created.
          example: '2022-12-06'
        credit_status:
          type:
            - string
            - 'null'
          enum:
            - available
            - consumed
            - voided
            - null
          description: |-
            The status of the credit portion of the credit note. It indicates the current state or condition of the credit amount associated with the credit note. The possible values for this field are:

            - `available`: this status indicates that an amount remains available for future usage. The credit can be applied towards future transactions or invoices.
            - `consumed`: this status indicates that the credit amount has been fully consumed. The remaining amount is 0, indicating that the credit has been utilized in its entirety.
            - `voided`: this status indicates that the remaining amount of the credit cannot be used any further. The credit has been voided and is no longer available for application or redemption.
          example: available
        refund_status:
          type:
            - string
            - 'null'
          enum:
            - pending
            - succeeded
            - failed
            - null
          description: |-
            The status of the refund portion of the credit note. It indicates the current state or condition of the refund associated with the credit note. The possible values for this field are:

            - `pending`: this status indicates that the refund is pending execution. The refund request has been initiated but has not been processed or completed yet.
            - `succeeded`: this status indicates that the refund has been successfully executed. The refund amount has been processed and returned to the customer or the designated recipient.
            - `failed`: this status indicates that the refund failed to execute. The refund request encountered an error or unsuccessful processing, and the refund amount could not be returned.
          example: pending
        reason:
          type: string
          enum:
            - duplicated_charge
            - product_unsatisfactory
            - order_change
            - order_cancellation
            - fraudulent_charge
            - other
          description: |-
            The reason of the credit note creation.
            Possible values are `duplicated_charge`, `product_unsatisfactory`, `order_change`, `order_cancellation`, `fraudulent_charge` or `other`.
          example: other
        description:
          type:
            - string
            - 'null'
          description: The description of the credit note.
          example: Free text
        currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of the credit note.
          example: EUR
        total_amount_cents:
          type: integer
          description: The total amount of the credit note, expressed in cents.
          example: 120
        taxes_amount_cents:
          type: integer
          description: The tax amount of the credit note, expressed in cents.
          example: 20
        taxes_rate:
          type: number
          description: The tax rate associated with this specific credit note.
          example: 20
        sub_total_excluding_taxes_amount_cents:
          type: integer
          description: The subtotal of the credit note excluding any applicable taxes, expressed in cents.
          example: 100
        balance_amount_cents:
          type: integer
          description: The remaining credit note amount, expressed in cents.
          example: 100
        credit_amount_cents:
          type: integer
          description: The credited amount of the credit note, expressed in cents.
          example: 100
        refund_amount_cents:
          type: integer
          description: The refunded amount of the credit note, expressed in cents.
          example: 0
        offset_amount_cents:
          type: integer
          description: The ofsetted amount (deducted from the invoice balance) of the credit note, expressed in cents.
          example: 0
        coupons_adjustment_amount_cents:
          type: integer
          description: The pro-rated amount of the coupons applied to the source invoice.
          example: 20
        created_at:
          type: string
          format: date-time
          description: The date when the credit note was created. It is expressed in Coordinated Universal Time (UTC).
          example: '2022-09-14T16:35:31Z'
        updated_at:
          type: string
          format: date-time
          description: The date when the credit note was last updated. It is expressed in Coordinated Universal Time (UTC).
          example: '2022-09-14T16:35:31Z'
        file_url:
          type:
            - string
            - 'null'
          description: The PDF file of the credit note.
          example: https://getlago.com/credit_note/file
        items:
          type: array
          items:
            $ref: '#/components/schemas/CreditNoteItemObject'
          description: Array of credit note's items.
        applied_taxes:
          type: array
          items:
            $ref: '#/components/schemas/CreditNoteAppliedTaxObject'
        self_billed:
          type: boolean
          example: false
          description: Indicates if the credit note belongs to self-billed invoice. Self-billing is a process where an organization creates the invoice on behalf of the partner.
        customer:
          $ref: '#/components/schemas/CustomerBaseObject'
        metadata:
          $ref: '#/components/schemas/MetadataObject'
        error_details:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CreditNoteErrorDetailsObject'
    CreditNotesPaginated:
      type: object
      required:
        - credit_notes
        - meta
      properties:
        credit_notes:
          type: array
          items:
            $ref: '#/components/schemas/CreditNoteObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    MetadataInput:
      type: object
      description: Metadata to set as key-value pairs. Keys are strings (max 100 characters), values can be strings (max 255 characters) or null.
      additionalProperties:
        type:
          - string
          - 'null'
      example:
        external_id: ext-123
        synced_at: '2024-01-15'
    CreditNoteCreateInput:
      type: object
      required:
        - credit_note
      properties:
        credit_note:
          type: object
          required:
            - invoice_id
            - items
          properties:
            invoice_id:
              type: string
              format: uuid
              description: The invoice unique identifier, created by Lago.
              example: 1a901a90-1a90-1a90-1a90-1a901a901a90
            reason:
              type:
                - string
                - 'null'
              enum:
                - duplicated_charge
                - product_unsatisfactory
                - order_change
                - order_cancellation
                - fraudulent_charge
                - other
                - null
              description: |-
                The reason of the credit note creation.
                Possible values are `duplicated_charge`, `product_unsatisfactory`, `order_change`, `order_cancellation`, `fraudulent_charge` or `other`.
              example: duplicated_charge
            description:
              type: string
              description: The description of the credit note.
              example: description
            credit_amount_cents:
              type:
                - integer
                - 'null'
              description: The total amount to be credited to the customer balance for discounts on future invoices. For a total or partial refund, credit or offset, the amount in cents must include both the item amount and the applicable tax. The refunded, credited and offsetted amounts should always balance. The total, including taxes, cannot exceed the invoice’s total fees.”
              example: 100
            refund_amount_cents:
              type:
                - integer
                - 'null'
              description: The total amount to be refunded immediately to the payment method used by the customer. For a total or partial refund, credit or offset, the amount in cents must include both the item amount and the applicable tax. The refunded, credited and offsetted amounts should always balance. The total, including taxes, cannot exceed the invoice’s total fees.”
              example: 500
            offset_amount_cents:
              type:
                - integer
                - 'null'
              description: The total amount to be immediately deducted from the invoice balance. For a total or partial refund, credit or offset, the amount in cents must include both the item amount and the applicable tax. The refunded, credited and offsetted amounts should always balance. The total, including taxes, cannot exceed the invoice’s total fees.”
              example: 200
            items:
              type: array
              items:
                type: object
                required:
                  - fee_id
                  - amount_cents
                properties:
                  fee_id:
                    type: string
                    format: uuid
                    description: The fee unique identifier, created by Lago.
                    example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                  amount_cents:
                    type: integer
                    description: This is the amount of the credit note item excluding taxes, expressed in cents.
                    example: 100
              description: The list of credit note's items.
              example:
                - fee_id: 1a901a90-1a90-1a90-1a90-1a901a901a90
                  amount_cents: 100
                - fee_id: 1a901a90-1a90-1a90-1a90-1a901a901a91
                  amount_cents: 500
                - fee_id: 1a901a90-1a90-1a90-1a90-1a901a901a92
                  amount_cents: 200
            metadata:
              $ref: '#/components/schemas/MetadataInput'
    CreditNoteExtendedObject:
      allOf:
        - $ref: '#/components/schemas/CreditNoteObject'
        - type: object
          properties:
            customer:
              $ref: '#/components/schemas/CustomerBaseObject'
    CreditNoteExtended:
      type: object
      required:
        - credit_note
      properties:
        credit_note:
          $ref: '#/components/schemas/CreditNoteExtendedObject'
    CreditNoteUpdateInput:
      type: object
      required:
        - credit_note
      properties:
        credit_note:
          type: object
          required:
            - refund_status
          properties:
            refund_status:
              type: string
              enum:
                - pending
                - succeeded
                - failed
              description: |-
                The status of the refund portion of the credit note. It indicates the current state or condition of the refund associated with the credit note. The possible values for this field are:

                - `pending`: this status indicates that the refund is pending execution. The refund request has been initiated but has not been processed or completed yet.
                - `succeeded`: this status indicates that the refund has been successfully executed. The refund amount has been processed and returned to the customer or the designated recipient.
                - `failed`: this status indicates that the refund failed to execute. The refund request encountered an error or unsuccessful processing, and the refund amount could not be returned.
              example: succeeded
            metadata:
              $ref: '#/components/schemas/MetadataInput'
    CreditNote:
      type: object
      required:
        - credit_note
      properties:
        credit_note:
          $ref: '#/components/schemas/CreditNoteObject'
    CreditNoteEstimateInput:
      type: object
      required:
        - credit_note
      properties:
        credit_note:
          type: object
          required:
            - invoice_id
            - items
          properties:
            invoice_id:
              type: string
              format: uuid
              description: The invoice unique identifier, created by Lago.
              example: 1a901a90-1a90-1a90-1a90-1a901a901a90
            items:
              type: array
              items:
                type: object
                required:
                  - fee_id
                  - amount_cents
                properties:
                  fee_id:
                    type: string
                    format: uuid
                    description: The fee unique identifier, created by Lago.
                    example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                  amount_cents:
                    type: integer
                    description: The amount of the credit note item, expressed in cents.
                    example: 10
              description: The list of credit note's items.
              example:
                - fee_id: 1a901a90-1a90-1a90-1a90-1a901a901a90
                  amount_cents: 10
                - fee_id: 1a901a90-1a90-1a90-1a90-1a901a901a91
                  amount_cents: 5
    CreditNoteEstimated:
      type: object
      required:
        - estimated_credit_note
      properties:
        estimated_credit_note:
          type: object
          required:
            - lago_invoice_id
            - invoice_number
            - currency
            - taxes_amount_cents
            - precise_taxes_amount_cents
            - sub_total_excluding_taxes_amount_cents
            - max_creditable_amount_cents
            - max_refundable_amount_cents
            - max_offsettable_amount_cents
            - coupons_adjustment_amount_cents
            - precise_coupons_adjustment_amount_cents
            - taxes_rate
            - items
          properties:
            lago_invoice_id:
              type: string
              format: uuid
              description: Unique identifier assigned to the invoice that the credit note belongs to
              example: 1a901a90-1a90-1a90-1a90-1a901a901a90
            invoice_number:
              type: string
              description: The invoice unique number, related to the credit note.
              example: LAG-1234
            currency:
              $ref: '#/components/schemas/Currency'
              description: The currency of the credit note.
              example: EUR
            taxes_amount_cents:
              type: integer
              description: The tax amount of the credit note, expressed in cents.
              example: 20
            precise_taxes_amount_cents:
              type: number
              description: The precise tax amount of the credit note, expressed in cents with decimal precision.
              example: 20.1
            taxes_rate:
              type: number
              description: The tax rate associated with this specific credit note.
              example: 20
            sub_total_excluding_taxes_amount_cents:
              type: integer
              description: The subtotal of the credit note excluding any applicable taxes, expressed in cents.
              example: 100
            max_creditable_amount_cents:
              type: integer
              description: The credited amount of the credit note, expressed in cents.
              example: 100
            max_refundable_amount_cents:
              type: integer
              description: The refunded amount of the credit note, expressed in cents.
              example: 0
            max_offsettable_amount_cents:
              type: integer
              description: The ofsetted amount of the credit note, expressed in cents.
              example: 0
            coupons_adjustment_amount_cents:
              type: integer
              description: The pro-rated amount of the coupons applied to the source invoice.
              example: 20
            precise_coupons_adjustment_amount_cents:
              type: number
              description: The precise pro-rated amount with decimal precision of the coupons applied to the source invoice.
              example: 20.1
            items:
              type: array
              items:
                type: object
                required:
                  - amount_cents
                  - lago_fee_id
                properties:
                  amount_cents:
                    type: integer
                    description: The credit note's item amount, expressed in cents.
                    example: 100
                  lago_fee_id:
                    type:
                      - string
                      - 'null'
                    format: uuid
                    description: Unique identifier assigned to the fee within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the fee's record within the Lago system.
                    example: 1a901a90-1a90-1a90-1a90-1a901a901a90
              description: Array of credit note's items.
            applied_taxes:
              type: array
              items:
                type: object
                properties:
                  lago_tax_id:
                    type: string
                    format: uuid
                    description: Unique identifier of the tax, created by Lago.
                    example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                  tax_name:
                    type: string
                    description: Name of the tax.
                    example: TVA
                  tax_code:
                    type: string
                    description: Unique code used to identify the tax associated with the API request.
                    example: french_standard_vat
                  tax_rate:
                    type: number
                    description: The percentage rate of the tax
                    example: 20
                  tax_description:
                    type: string
                    description: Internal description of the taxe
                    example: French standard VAT
                  base_amount_cents:
                    type: integer
                    example: 100
                  amount_cents:
                    type: integer
                    description: Amount of the tax
                    example: 2000
                  amount_currency:
                    $ref: '#/components/schemas/Currency'
                    description: Currency of the tax
                    example: USD
    ApiErrorNotAllowed:
      type: object
      required:
        - status
        - error
        - code
      properties:
        status:
          type: integer
          format: int32
          example: 405
        error:
          type: string
          example: Method Not Allowed
        code:
          type: string
          example: not_allowed
    CreditNoteMetadataResponse:
      type: object
      required:
        - metadata
      properties:
        metadata:
          $ref: '#/components/schemas/MetadataObject'
    IntegrationCustomer:
      type: object
      required:
        - lago_id
        - type
        - external_customer_id
        - integration_code
      description: Configuration specific to the accounting and tax integrations. This object contains settings and parameters necessary for syncing documents and payments.
      properties:
        lago_id:
          type: string
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: A unique identifier for the integration customer object in the Lago application.
        type:
          type: string
          example: netsuite
          description: |-
            The integration type used for accounting and tax syncs.
            Accepted values: `netsuite, anrok`.
          enum:
            - netsuite
            - anrok
            - xero
            - hubspot
            - salesforce
        integration_code:
          type: string
          example: netsuite-eu-1
          description: Unique code used to identify an integration connection.
        external_customer_id:
          type: string
          example: cus_12345
          description: The customer ID within the integration's system. If this field is not provided, Lago has the option to create a new customer record within the integration's system on behalf of the customer.
        sync_with_provider:
          type:
            - boolean
            - 'null'
          example: true
          description: Set this field to `true` if you want to create a customer record in the integration's system. This option is applicable only when the `external_customer_id` is null and the `sync_with_provider` field is set to `true`. By default, the value is set to `false`
        subsidiary_id:
          type: string
          example: '2'
          description: This optional field is needed only when working with `netsuite` connection.
        targeted_object:
          type:
            - string
            - 'null'
          example: contacts
          description: This optional field is present only when working with `hubspot` connection.
        email:
          type:
            - string
            - 'null'
          example: dinesh@piedpiper.test
          description: This optional field is present only when working with `hubspot` connection.
    CustomerObject:
      allOf:
        - $ref: '#/components/schemas/CustomerBaseObject'
        - type: object
          properties:
            integration_customers:
              type: array
              items:
                $ref: '#/components/schemas/IntegrationCustomer'
    ErrorDetailObject:
      type: object
      required:
        - lago_id
        - error_code
        - details
      properties:
        lago_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Unique identifier assigned to the error_detail within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the error's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        error_code:
          type: string
          description: Code that specifies part of the application / connection, where the error originally happened
          example: tax_error
        details:
          type: object
          description: Key value list of more elaborated error detail, where by the key of error_code an external service error details are stored
          example:
            tax_error: taxDateTooFarInFuture
          additionalProperties:
            type: string
    CustomerObjectExtended:
      allOf:
        - $ref: '#/components/schemas/CustomerObject'
        - type: object
          properties:
            metadata:
              type: array
              items:
                $ref: '#/components/schemas/CustomerMetadata'
            taxes:
              description: List of customer taxes
              type: array
              items:
                $ref: '#/components/schemas/TaxObject'
            applicable_invoice_custom_sections:
              description: The customer’s invoice custom section used for generating invoices.
              type: array
              items:
                $ref: '#/components/schemas/InvoiceCustomSectionObject'
            error_details:
              description: List of errors with details that might have been raised while processing backgroud actions for the customers
              type: array
              items:
                $ref: '#/components/schemas/ErrorDetailObject'
    CustomersPaginated:
      type: object
      required:
        - customers
        - meta
      properties:
        customers:
          type: array
          items:
            $ref: '#/components/schemas/CustomerObjectExtended'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    CustomerCreateInput:
      type: object
      required:
        - customer
      properties:
        customer:
          type: object
          required:
            - external_id
          properties:
            external_id:
              type: string
              example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
              description: The customer external unique identifier (provided by your own application)
            billing_entity_code:
              type:
                - string
                - 'null'
              example: acme_corp
              description: The unique code of the billing entity to associate with the customer. If not provided, the default billing entity will be used.
            address_line1:
              type:
                - string
                - 'null'
              example: 5230 Penfield Ave
              description: The first line of the billing address
            address_line2:
              type:
                - string
                - 'null'
              example: ''
              description: The second line of the billing address
            city:
              type:
                - string
                - 'null'
              example: Woodland Hills
              description: The city of the customer's billing address
            country:
              $ref: '#/components/schemas/CountryOrNull'
              description: Country code of the customer's billing address. Format must be ISO 3166 (alpha-2)
              example: US
            currency:
              $ref: '#/components/schemas/CurrencyOrNull'
              description: Currency of the customer. Format must be ISO 4217
            email:
              type:
                - string
                - 'null'
              format: email
              example: dinesh@piedpiper.test
              description: The email of the customer
            legal_name:
              type:
                - string
                - 'null'
              example: Coleman-Blair
              description: The legal company name of the customer
            legal_number:
              type:
                - string
                - 'null'
              example: 49-008-2965
              description: The legal company number of the customer
            logo_url:
              type:
                - string
                - 'null'
              example: http://hooli.com/logo.png
              description: The logo URL of the customer
            name:
              type:
                - string
                - 'null'
              maxLength: 255
              example: Gavin Belson
              description: The full name of the customer (255 characters max).
            firstname:
              type:
                - string
                - 'null'
              example: Gavin
              description: First name of the customer
            lastname:
              type:
                - string
                - 'null'
              example: Belson
              description: Last name of the customer
            account_type:
              type:
                - string
                - 'null'
              enum:
                - customer
                - partner
                - null
              example: customer
              description: |-
                The type of the account. It can have one of the following values:
                - `customer`: the account is a customer, default value.
                - `partner`: the account is a partner.
            customer_type:
              type:
                - string
                - 'null'
              enum:
                - company
                - individual
                - null
              description: |-
                The type of the customer. It can have one of the following values:
                - `company`: the customer is a company.
                - `individual`: the customer is an individual.
            phone:
              type:
                - string
                - 'null'
              example: 1-171-883-3711 x245
              description: The phone number of the customer
            state:
              type:
                - string
                - 'null'
              example: CA
              description: The state of the customer's billing address
            tax_codes:
              $ref: '#/components/schemas/TaxCodes'
            tax_identification_number:
              type:
                - string
                - 'null'
              example: EU123456789
              description: The tax identification number of the customer
            timezone:
              $ref: '#/components/schemas/TimezoneOrNull'
              description: The customer's timezone, used for billing purposes in their local time. Overrides the organization's timezone
            url:
              type:
                - string
                - 'null'
              example: http://hooli.com
              description: The custom website URL of the customer
            zipcode:
              type:
                - string
                - 'null'
              example: '91364'
              description: The zipcode of the customer's billing address
            net_payment_term:
              type:
                - integer
                - 'null'
              example: 30
              description: The net payment term, expressed in days, specifies the duration within which a customer is expected to remit payment after the invoice is finalized.
            finalize_zero_amount_invoice:
              type: string
              enum:
                - inherit
                - skip
                - finalize
              example: inherit
              description: |-
                Specifies how invoices with a zero total amount should be handled:
                - `inherit`: (Default) Follows the organization-level configuration.
                - `finalize`: Invoices are issued and finalized even if the total amount is zero.
                - `skip`: Invoices with a total amount of zero are not finalized.
            billing_configuration:
              $ref: '#/components/schemas/CustomerBillingConfiguration'
            shipping_address:
              $ref: '#/components/schemas/Address'
            integration_customers:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                    description: A unique identifier for the integration customer object in the Lago application.
                  integration_type:
                    type: string
                    example: netsuite
                    description: |-
                      The integration type used for accounting and tax syncs.
                      Accepted values: `netsuite, anrok, xero`.
                    enum:
                      - netsuite
                      - anrok
                      - xero
                  integration_code:
                    type: string
                    example: netsuite-eu-1
                    description: Unique code used to identify an integration connection.
                  external_customer_id:
                    type: string
                    example: cus_12345
                    description: The customer ID within the integration's system. If this field is not provided, Lago has the option to create a new customer record within the integration's system on behalf of the customer.
                  sync_with_provider:
                    type: boolean
                    example: true
                    description: Set this field to `true` if you want to create a customer record in the integration's system. This option is applicable only when the `external_customer_id` is null and the `sync_with_provider` field is set to `true`. By default, the value is set to `false`
                  subsidiary_id:
                    type: string
                    example: '2'
                    description: This optional field is needed only when working with `netsuite` connection.
            metadata:
              type: array
              description: Set of key-value pairs that you can attach to a customer. This can be useful for storing additional information about the customer in a structured format
              items:
                type: object
                required:
                  - key
                  - value
                  - display_in_invoice
                properties:
                  id:
                    type: string
                    format: uuid
                    example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                    description: Identifier for the metadata object, only required when updating a key-value pair
                  key:
                    type: string
                    example: Purchase Order
                    description: The metadata object key
                  value:
                    type: string
                    example: '123456789'
                    description: The metadata object value
                  display_in_invoice:
                    type: boolean
                    example: true
                    description: Determines whether the item or information should be displayed in the invoice. If set to true, the item or information will be included and visible in the generated invoice. If set to false, the item or information will be excluded and not displayed in the invoice.
            skip_invoice_custom_sections:
              type: boolean
              example: false
              description: Set to `true` to exclude all invoice custom sections from PDF generation for this customer only. False by default
            invoice_custom_section_codes:
              type: array
              items:
                type: string
              description: List of unique codes identifying the invoice custom sections.
              example:
                - eu_bank_details
    Customer:
      type: object
      required:
        - customer
      properties:
        customer:
          $ref: '#/components/schemas/CustomerObjectExtended'
    InvoiceBaseObject:
      type: object
      required:
        - lago_id
        - billing_entity_code
        - number
        - issuing_date
        - invoice_type
        - status
        - payment_status
        - currency
        - fees_amount_cents
        - coupons_amount_cents
        - credit_notes_amount_cents
        - sub_total_excluding_taxes_amount_cents
        - taxes_amount_cents
        - sub_total_including_taxes_amount_cents
        - prepaid_credit_amount_cents
        - progressive_billing_credit_amount_cents
        - total_amount_cents
        - version_number
        - created_at
        - updated_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the fee within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the fee's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        billing_entity_code:
          type:
            - string
            - 'null'
          example: acme_corp
          description: The unique code of the billing entity associated with the invoice
        sequential_id:
          type: integer
          description: This ID helps in uniquely identifying and organizing the invoices associated with a specific customer. It provides a sequential numbering system specific to the customer, allowing for easy tracking and management of invoices within the customer's context.
          example: 2
        number:
          type: string
          description: The unique number assigned to the invoice. This number serves as a distinct identifier for the invoice and helps in differentiating it from other invoices in the system.
          example: LAG-1234-001-002
        issuing_date:
          type: string
          format: date
          description: The date when the invoice was issued. It is provided in the ISO 8601 date format.
          example: '2022-04-30'
        payment_dispute_lost_at:
          type: string
          format: date-time
          description: The date when the payment dispute was lost. It is expressed in Coordinated Universal Time (UTC).
          example: '2022-09-14T16:35:31Z'
        payment_due_date:
          type: string
          format: date
          description: The payment due date for the invoice, specified in the ISO 8601 date format.
          example: '2022-04-30'
        payment_overdue:
          type: boolean
          description: Specifies if the payment is considered as overdue.
          example: true
        net_payment_term:
          type: integer
          example: 30
          description: The net payment term, expressed in days, specifies the duration within which a customer is expected to remit payment after the invoice is finalized.
        invoice_type:
          type: string
          enum:
            - subscription
            - add_on
            - credit
            - one_off
            - progressive_billing
          description: The type of invoice issued. Possible values are `subscription`, `one-off`, `credit` or `progressive_billing`.
          example: subscription
        status:
          type: string
          enum:
            - draft
            - finalized
            - voided
            - failed
            - pending
            - deleted
          description: |-
            The status of the invoice. It indicates the current state of the invoice and can have following values:
            - `draft`: the invoice is in the draft state, waiting for the end of the grace period to be finalized. During this period, events can still be ingested and added to the invoice.
            - `finalized`: the invoice has been issued and finalized. In this state, events cannot be ingested or added to the invoice anymore.
            - `voided`: the invoice has been issued and subsequently voided. In this state, events cannot be ingested or added to the invoice anymore.
            - `pending`: the invoice remains pending until the taxes are fetched from the external provider.
            - `failed`: during an attempt of finalization of the invoice, an error happened. This invoice will have an array of error_details, explaining, in which part of the system an error happened and how it's possible to fix it. This invoice can't be edited or updated, only retried. This action will discard current error_details and will create new ones if the finalization failed again.
            - `deleted`: the draft invoice has been permanently deleted. This status is only returned by the delete endpoint and its webhook; a deleted invoice is no longer retrievable afterwards.
          example: finalized
        payment_status:
          type: string
          enum:
            - pending
            - succeeded
            - failed
          description: |-
            The status of the payment associated with the invoice. It can have one of the following values:
            - `pending`: the payment is pending, waiting for payment processing in Stripe or when the invoice is emitted but users have not updated the payment status through the endpoint.
            - `succeeded`: the payment of the invoice has been successfully processed.
            - `failed`: the payment of the invoice has failed or encountered an error during processing.
          example: succeeded
        currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of the invoice issued.
          example: EUR
        fees_amount_cents:
          type: integer
          description: The total sum of fees amount in cents. It calculates the cumulative amount of all the fees associated with the invoice, providing a consolidated value.
          example: 100
        coupons_amount_cents:
          type: integer
          description: The total sum of all coupons discounted on the invoice. It calculates the cumulative discount amount applied by coupons, expressed in cents.
          example: 10
        credit_notes_amount_cents:
          type: integer
          description: The total sum of all credit notes discounted on the invoice. It calculates the cumulative discount amount applied by credit notes, expressed in cents.
          example: 10
        sub_total_excluding_taxes_amount_cents:
          type: integer
          description: |-
            Subtotal amount, excluding taxes, expressed in cents.
            This field depends on the version number. Here are the definitions based on the version:
            - Version 1: is equal to the sum of `fees_amount_cents`, minus `coupons_amount_cents`, and minus `prepaid_credit_amount_cents`.
            - Version 2: is equal to the `fees_amount_cents`.
            - Version 3 & 4: is equal to the `fees_amount_cents`, minus `coupons_amount_cents`
          example: 100
        taxes_amount_cents:
          type: integer
          description: The sum of tax amount associated with the invoice, expressed in cents.
          example: 20
        sub_total_including_taxes_amount_cents:
          type: integer
          description: |-
            Subtotal amount, including taxes, expressed in cents.
            This field depends on the version number. Here are the definitions based on the version:
            - Version 1: is equal to the `total_amount_cents`.
            - Version 2: is equal to the sum of `fees_amount_cents` and `taxes_amount_cents`.
            - Version 3 & 4: is equal to the sum `sub_total_excluding_taxes_amount_cents` and `taxes_amount_cents`
          example: 120
        prepaid_credit_amount_cents:
          type: integer
          description: The total sum of all prepaid credits discounted on the invoice. It calculates the cumulative discount amount applied by prepaid credits, expressed in cents.
          example: 0
        prepaid_granted_credit_amount_cents:
          type:
            - integer
            - 'null'
          description: The portion of prepaid credits discounted on the invoice that originated from granted (free) credits, expressed in cents. Only populated for invoices associated with traceable wallets.
          example: 0
        prepaid_purchased_credit_amount_cents:
          type:
            - integer
            - 'null'
          description: The portion of prepaid credits discounted on the invoice that originated from purchased (paid) credits, expressed in cents. Only populated for invoices associated with traceable wallets.
          example: 0
        progressive_billing_credit_amount_cents:
          type: integer
          description: The usage already billed in previous invoices. Only apply to `progressive_billing` and `subscription` invoices.
          example: 0
        total_amount_cents:
          type: integer
          description: The sum of the amount and taxes amount on the invoice, expressed in cents. It calculates the total financial value of the invoice, including both the original amount and any applicable taxes.
          example: 100
        version_number:
          type: integer
          example: 3
        self_billed:
          type: boolean
          example: false
          description: Indicates if the invoice is self-billed. Self-billing is a process where an organization creates the invoice on behalf of the partner. This field specifies whether the invoice is self-billed or not.
        file_url:
          type: string
          format: uri
          description: Contains the URL that provides direct access to the invoice PDF file. You can use this URL to download or view the PDF document of the invoice
          example: https://getlago.com/invoice/file
        web_url:
          type:
            - string
            - 'null'
          format: uri
          description: Contains the URL to the invoice page in the Lago dashboard. It is `null` for invoices that are not visible in the dashboard (for example while still generating). Use it to link users directly to the invoice overview page.
          example: https://app.getlago.com/acme/customer/1a901a90-1a90-1a90-1a90-1a901a901a90/invoice/2b012b01-2b01-2b01-2b01-2b012b012b01/overview
        created_at:
          type: string
          format: date-time
          example: '2022-04-29T08:59:51Z'
          description: The date of the invoice creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). The creation_date provides a standardized and internationally recognized timestamp for when the invoice object was created
        updated_at:
          type: string
          format: date-time
          example: '2022-04-29T08:59:51Z'
          description: The date of the invoice update, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). The update_date provides a standardized and internationally recognized timestamp for when the invoice object was updated
    InvoiceMetadataObject:
      type: object
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the invoice metadata within the Lago application.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        key:
          type: string
          description: Represents the key of the metadata's key-value pair.
          example: digital_ref_id
        value:
          type: string
          maxLength: 140
          description: Represents the value of the metadata's key-value pair (140 characters max).
          example: INV-0123456-98765
        created_at:
          type: string
          format: date-time
          description: The date and time when the metadata object was created. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
          example: '2022-04-29T08:59:51Z'
    InvoiceAppliedTaxObject:
      allOf:
        - $ref: '#/components/schemas/BaseAppliedTax'
      type: object
      properties:
        lago_invoice_id:
          type: string
          format: uuid
          description: Unique identifier of the invoice, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        fees_amount_cents:
          type: integer
          description: Fees total amount on which the tax is applied
          example: 20000
    InvoiceAppliedInvoiceCustomSectionObject:
      type: object
      required:
        - lago_id
        - lago_invoice_id
        - code
        - details
        - display_name
        - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the applied invoice custom section in the Lago application.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_invoice_id:
          type: string
          format: uuid
          description: Unique identifier of the invoice this custom section is applied to.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        code:
          type: string
          description: Unique code identifying the invoice custom section.
          example: eu_bank_details
        details:
          type: string
          description: The value shown on the invoice PDF.
          example: 'Bank Name: Lago Bank, IBAN: FR7630004000031234567890143'
        display_name:
          type: string
          description: The name of the invoice custom section displayed on the invoice.
          example: 'Bank Details:'
        created_at:
          type: string
          format: date-time
          description: The date of the applied invoice custom section creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
          example: '2023-07-06T14:35:58Z'
    UsageThresholdObject:
      type: object
      required:
        - lago_id
        - threshold_display_name
        - amount_cents
        - recurring
        - created_at
        - updated_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the usage threshold created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        threshold_display_name:
          type:
            - string
            - 'null'
          description: The display name of the usage threshold.
          example: Threshold 1
        amount_cents:
          type: integer
          description: The amount to reach to trigger a `progressive_billing` invoice.
          example: 10000
        recurring:
          type: boolean
          description: This field when set to `true` indicates that a `progressive_billing` invoice will be created every time the lifetime usage increases by the specified amount.
          example: true
        created_at:
          type: string
          format: date-time
          description: The date and time when the usage threshold was created. It is expressed in UTC format according to the ISO 8601 datetime standard.
          example: '2023-06-27T19:43:42Z'
        updated_at:
          type: string
          format: date-time
          description: The date and time when the usage threshold was last updated. It is expressed in UTC format according to the ISO 8601 datetime standard.
          example: '2023-06-27T19:43:42Z'
    AppliedUsageThresholdObject:
      type: object
      required:
        - lifetime_usage_amount_cents
        - created_at
        - usage_threshold
      properties:
        lifetime_usage_amount_cents:
          type: integer
          description: The amount of usage in cents that has been accumulated over the lifetime of the subscription.
          example: 2000
        created_at:
          type: string
          format: date-time
          description: The date and time when the lifetime usage was computed. It is expressed in UTC format according to the ISO 8601 datetime standard.
          example: '2025-03-31T12:31:44Z'
        usage_threshold:
          $ref: '#/components/schemas/UsageThresholdObject'
    InvoiceObject:
      allOf:
        - $ref: '#/components/schemas/InvoiceBaseObject'
        - type: object
          properties:
            customer:
              $ref: '#/components/schemas/CustomerObject'
              description: The customer on which the invoice applies. It refers to the customer account or entity associated with the invoice.
            metadata:
              type: array
              items:
                $ref: '#/components/schemas/InvoiceMetadataObject'
            applied_taxes:
              type: array
              items:
                $ref: '#/components/schemas/InvoiceAppliedTaxObject'
            applied_invoice_custom_sections:
              description: The invoice custom sections applied to this invoice for PDF generation.
              type: array
              items:
                $ref: '#/components/schemas/InvoiceAppliedInvoiceCustomSectionObject'
            applied_usage_thresholds:
              type: array
              items:
                $ref: '#/components/schemas/AppliedUsageThresholdObject'
    InvoicesPaginated:
      type: object
      required:
        - invoices
        - meta
      properties:
        invoices:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    PaymentObject:
      type: object
      required:
        - lago_id
        - lago_customer_id
        - external_customer_id
        - invoice_ids
        - lago_payable_id
        - payable_type
        - amount_cents
        - amount_currency
        - status
        - payment_status
        - type
        - reference
        - payment_provider_code
        - payment_provider_type
        - external_payment_id
        - provider_payment_id
        - provider_customer_id
        - next_action
        - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: The unique identifier of the payment, created by Lago.
          example: 4cf085a7-c196-4f07-a543-97c50ec6e8b2
        lago_customer_id:
          type: string
          format: uuid
          description: Unique identifier of the customer, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_customer_id:
          type: string
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
          description: The customer external unique identifier (provided by your own application)
        invoice_ids:
          type: array
          description: List of invoice IDs associated with the payment.
          items:
            type: string
            format: uuid
            example: 486b147a-02a1-4ccf-8603-f3541fc25e7a
        invoice_numbers:
          type: array
          description: List of invoice numbers associated with the payment.
          items:
            type: string
            example: HOO-202D-005-001
        lago_payable_id:
          type: string
          format: uuid
          description: The unique identifier of the paid resource, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        payable_type:
          type: string
          enum:
            - Invoice
            - PaymentRequest
          description: The type of the paid resource, associated with the `lago_payable_id`.
          example: Invoice
        amount_cents:
          type: integer
          description: The amount of the payment in cents.
          example: 1099
        amount_currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of the payment amount.
          example: USD
        status:
          type: string
          description: The status of the payment within the payment provider. This can be very different from a payment provider to another.
          example: Completed
        payment_status:
          type: string
          description: The normalized payment status by Lago.
          enum:
            - succeeded
            - failed
            - pending
            - processing
          example: succeeded
        type:
          type: string
          description: The type of payment.
          enum:
            - manual
            - provider
          example: manual
        reference:
          type: string
          description: Reference for the payment.
          example: ref1
        payment_provider_code:
          type: string
          description: Code of the payment provider
          example: stripe_prod
        payment_provider_type:
          type: string
          enum:
            - adyen
            - cashfree
            - gocardless
            - stripe
            - flutterwave
            - moneyhash
          description: The type of payment provider
          example: stripe
        external_payment_id:
          type:
            - string
            - 'null'
          description: 'DEPRECATED: use provider_payment_id'
        provider_payment_id:
          type:
            - string
            - 'null'
          description: Unique identifier of the payment within the payment provider (if applicable).
          example: pi_5eb0285741bc6ba
        provider_customer_id:
          type: string
          description: Unique identifier of the customer within the payment provider
          example: cus_5eb0285bcf941bc6ba
        payment_method_id:
          type:
            - string
            - 'null'
          format: uuid
          description: The unique identifier of the payment method used for this payment.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        next_action:
          type: object
          additionalProperties: true
          description: The next action to be taken by the customer to complete the payment. Should usually be empty, except when receiving the `payment.requires_action` webhook.
          example:
            type: redirect_to_url
            redirect_to_url:
              url: https://hooks.stripe.com/3d_secure_2/hosted?merchant=acct_AAA&payment_intent=pi_BBB&payment_intent_client_secret=pi_BBB&publishable_key=pk_test_CCC
              return_url: https://app.example.com
        created_at:
          type: string
          format: date-time
          description: Timestamp when the payment was created in Lago's database, not on the payment provider.
          example: '2025-01-21T00:10:29Z'
    PaymentsPaginated:
      type: object
      required:
        - payments
        - meta
      properties:
        payments:
          type: array
          items:
            $ref: '#/components/schemas/PaymentObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    PaymentRequestObject:
      type: object
      required:
        - lago_id
        - email
        - amount_cents
        - amount_currency
        - payment_status
        - created_at
        - customer
        - invoices
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the payment request, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        email:
          type: string
          format: email
          example: dinesh@piedpiper.test
          description: The customer's email address used for sending dunning notifications
        amount_cents:
          type: integer
          description: The sum of the total amounts of all the invoices included in the payment request, expressed in cents.
          example: 100
        amount_currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of the payment request.
          example: EUR
        payment_status:
          type: string
          enum:
            - pending
            - succeeded
            - failed
          description: |-
            The status of the payment associated with the payment request. It can have one of the following values:
            - `pending`: the payment is pending, waiting for payment processing in the payment provider or when the invoice is emitted but users have not updated the payment status through the endpoint.
            - `succeeded`: the payment of the payment request has been successfully processed.
            - `failed`: the payment of the payment request has failed or encountered an error during processing.
          example: succeeded
        created_at:
          type: string
          format: date-time
          description: The date and time when the payment request was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the payment request was initially created.
          example: '2022-04-29T08:59:51Z'
        customer:
          $ref: '#/components/schemas/CustomerBaseObject'
          description: The customer on which the payment request applies. It refers to the customer account or entity associated with the payment request.
        invoices:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceBaseObject'
    PaymentRequestsPaginated:
      type: object
      required:
        - payment_requests
        - meta
      properties:
        payment_requests:
          type: array
          items:
            $ref: '#/components/schemas/PaymentRequestObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    AppliedInvoiceCustomSectionObject:
      type: object
      required:
        - lago_id
        - created_at
        - invoice_custom_section
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the applied invoice custom section in the Lago application.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        created_at:
          type: string
          format: date-time
          description: The date of the applied invoice custom section creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
          example: '2023-07-06T14:35:58Z'
        invoice_custom_section_id:
          deprecated: true
          type: string
          format: uuid
          description: '**Deprecated.** Unique identifier of the invoice custom section that was applied.'
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        invoice_custom_section:
          $ref: '#/components/schemas/InvoiceCustomSectionObject'
    PaymentMethodReference:
      type: object
      description: Reference to a specific payment method for processing the payment.
      properties:
        payment_method_type:
          type: string
          enum:
            - provider
            - manual
          description: The type of payment method to use.
          example: provider
        payment_method_id:
          type: string
          format: uuid
          description: The unique identifier of the payment method (required when using a specific provider payment method).
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
    SubscriptionActivationRuleObject:
      type: object
      required:
        - lago_id
        - type
        - timeout_hours
        - status
        - created_at
        - updated_at
      properties:
        lago_id:
          type: string
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: Unique identifier assigned to the activation rule within the Lago application. This ID is exclusively created by Lago.
        type:
          type: string
          description: The type of the activation rule. Only `payment` is currently supported. A `payment` rule gates the subscription activation on a successful payment of the first invoice.
          example: payment
          enum:
            - payment
        timeout_hours:
          type: integer
          description: The number of hours the subscription stays in the `incomplete` state waiting for the payment to succeed before it is automatically canceled.
          example: 48
        status:
          type: string
          description: |-
            The evaluation status of the activation rule:
            - `inactive`: the rule has not been evaluated yet.
            - `pending`: the rule is applicable and is waiting to be satisfied (e.g. waiting for the payment).
            - `satisfied`: the rule has been satisfied and no longer blocks activation.
            - `declined`: the rule was applicable but was declined.
            - `failed`: the rule could not be satisfied (e.g. the payment failed).
            - `expired`: the rule was not satisfied before its timeout elapsed.
            - `not_applicable`: the rule did not apply to this subscription.
          example: pending
          enum:
            - inactive
            - pending
            - satisfied
            - declined
            - failed
            - expired
            - not_applicable
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2022-08-10T00:00:00Z'
          description: The date and time when the rule expires, after which an unsatisfied rule causes the subscription to be canceled. Represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). Null until the rule starts being evaluated.
        created_at:
          type: string
          format: date-time
          example: '2022-08-08T00:00:00Z'
          description: The creation date of the activation rule, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
        updated_at:
          type: string
          format: date-time
          example: '2022-08-08T00:00:00Z'
          description: The last update date of the activation rule, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
    SubscriptionObject:
      type: object
      required:
        - billing_time
        - canceled_at
        - created_at
        - current_billing_period_ending_at
        - current_billing_period_started_at
        - downgrade_plan_date
        - ending_at
        - external_customer_id
        - external_id
        - lago_customer_id
        - lago_id
        - name
        - next_plan_code
        - on_termination_credit_note
        - on_termination_invoice
        - plan_code
        - previous_plan_code
        - started_at
        - status
        - subscription_at
        - terminated_at
        - trial_ended_at
      properties:
        lago_id:
          type: string
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: Unique identifier assigned to the subscription within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the subscription's record within the Lago system
        external_id:
          type: string
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
          description: The subscription external unique identifier (provided by your own application).
        lago_customer_id:
          type: string
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer's record within the Lago system
        external_customer_id:
          type: string
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
          description: The customer external unique identifier (provided by your own application).
        billing_entity_code:
          type: string
          example: default
          description: The code of the billing entity associated with the subscription.
        billing_time:
          type: string
          description: The billing time for the subscription, which can be set as either `anniversary` or `calendar`. If not explicitly provided, it will default to `calendar`. The billing time determines the timing of recurring billing cycles for the subscription. By specifying `anniversary`, the billing cycle will be based on the specific date the subscription started (billed fully), while `calendar` sets the billing cycle at the first day of the week/month/year (billed with proration).
          example: anniversary
          enum:
            - calendar
            - anniversary
        name:
          type:
            - string
            - 'null'
          example: Repository A
          description: The display name of the subscription on an invoice. This field allows for customization of the subscription's name for billing purposes, especially useful when a single customer has multiple subscriptions using the same plan.
        plan_code:
          type: string
          example: premium
          description: The unique code representing the plan to be attached to the customer. This code must correspond to the `code` property of one of the active plans.
        plan_amount_cents:
          type: integer
          description: The base cost of the related plan, excluding any applicable taxes, that is billed on a recurring basis.
          example: 10000
        plan_amount_currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of the related plan. It indicates the monetary unit in which the plan's cost, including taxes and usage-based charges, is expressed.
          example: USD
        status:
          type: string
          description: |-
            The status of the subscription, which can have the following values:
            - `active`: the subscription is currently active and applied to the customer.
            - `canceled`: the subscription has been stopped before its activation. This can occur when two consecutive downgrades have been applied to a customer, when a subscription with a pending status is terminated, or when a payment-gated subscription fails to be paid (or its activation rule expires) before activation. When caused by payment gating, the `cancellation_reason` field is set.
            - `incomplete`: the subscription was created with a payment activation rule and is waiting for the gating payment to succeed before it becomes `active`. It is automatically `canceled` if the payment fails or the activation rule expires.
            - `pending`: a previous subscription has been downgraded, and the current one is awaiting automatic activation at the end of the billing period.
            - `terminated`: the subscription is no longer active.
          example: active
          enum:
            - active
            - canceled
            - incomplete
            - pending
            - terminated
        created_at:
          type: string
          format: date-time
          example: '2022-08-08T00:00:00Z'
          description: The creation date of the subscription, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). This date provides a timestamp indicating when the subscription was initially created.
        canceled_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2022-09-14T16:35:31Z'
          description: The cancellation date of the subscription. This field is not null when the subscription is `canceled`. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
        started_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2022-08-08T00:00:00Z'
          description: The effective start date of the subscription. This field can be null if the subscription is `pending` or `canceled`. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
        ending_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2022-10-08T00:00:00Z'
          description: The effective end date of the subscription. If this field is set to null, the subscription will automatically renew. This date should be provided in ISO 8601 datetime format, and use Coordinated Universal Time (UTC).
        subscription_at:
          type: string
          format: date-time
          example: '2022-08-08T00:00:00Z'
          description: The anniversary date and time of the initial subscription. This date serves as the basis for billing subscriptions with `anniversary` billing time. The `anniversary_date` should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
        terminated_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2022-09-14T16:35:31Z'
          description: The termination date of the subscription. This field is not null when the subscription is `terminated`. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC)
        previous_plan_code:
          type:
            - string
            - 'null'
          example: null
          description: The code identifying the previous plan associated with this subscription.
        next_plan_code:
          type:
            - string
            - 'null'
          example: null
          description: The code identifying the next plan in the case of a downgrade.
        downgrade_plan_date:
          type:
            - string
            - 'null'
          format: date
          example: '2022-04-30'
          description: The date when the plan will be downgraded, represented in ISO 8601 date format.
        trial_ended_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2022-08-08T00:00:00Z'
          description: The date when the free trial is ended, represented in ISO 8601 date format.
        current_billing_period_started_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2022-08-08T00:00:00Z'
          description: The date and time when the current billing period started, represented in ISO 8601 date format.
        current_billing_period_ending_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2022-09-08T00:00:00Z'
          description: The date and time when the current billing period ends, represented in ISO 8601 date format.
        on_termination_credit_note:
          type:
            - string
            - 'null'
          description: |
            When a pay-in-advance subscription is terminated before the end of its billing period, we generate a credit note for the unused subscription time by default.
            This field allows you to control the behavior of the credit note generation:

            - `credit`: A credit note is generated for the unused subscription time. The unused amount is credited back to the customer.
            - `refund`: A credit note is generated for the unused subscription time. If the invoice is paid or partially paid, the unused paid amount is refunded; any unpaid unused amount is credited back to the customer.
            - `offset`: A credit note is generated for the unused subscription time. If the invoice is paid or partially paid, the unused paid amount is refunded; any unpaid unused amount is applied to the invoice reducing its amount due.
            - `skip`: No credit note is generated for the unused subscription time.

            _Note: This field is only applicable to pay-in-advance plans and will be `null` for pay-in-arrears plans._
          example: credit
          enum:
            - credit
            - refund
            - offset
            - skip
        on_termination_invoice:
          type:
            - string
          example: generate
          enum:
            - generate
            - skip
          default: generate
          description: |
            When a subscription is terminated before the end of its billing period, we generate an invoice for the unbilled usage.
            This field allows you to control the behavior of the invoice generation:

            - `generate`: An invoice is generated for the unbilled usage.
            - `skip`: No invoice is generated for the unbilled usage.
        applied_invoice_custom_sections:
          description: The invoice custom sections applied to invoices generated by this subscription.
          type: array
          items:
            $ref: '#/components/schemas/AppliedInvoiceCustomSectionObject'
        payment_method:
          $ref: '#/components/schemas/PaymentMethodReference'
          description: The payment method assigned to this subscription for processing payments.
        consolidate_invoice:
          type: boolean
          default: true
          example: true
          description: |
            Controls whether this subscription is eligible to be grouped with other subscriptions of the same customer on a consolidated recurring invoice.

            - `true` (default): the subscription is included in the customer's standard invoice grouping (by billing entity, currency and payment method).
            - `false`: the subscription is excluded from consolidation and always billed on its own dedicated invoice, regardless of other grouping criteria.
        cancellation_reason:
          type:
            - string
            - 'null'
          example: payment_failed
          enum:
            - payment_failed
            - timeout
          description: |
            The reason a payment-gated subscription was canceled before activation. Null unless the subscription was canceled by payment gating.

            - `payment_failed`: the gating payment failed.
            - `timeout`: the activation rule expired before the payment succeeded.
        activated_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2022-08-08T00:00:00Z'
          description: |
            The date and time when a payment-gated subscription was activated (i.e. moved from `incomplete` to `active` once the gating payment succeeded), represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). Null while the subscription is still `incomplete`.
        activation_rules:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionActivationRuleObject'
          description: |
            The activation rules attached to the subscription. A payment activation rule gates activation on a successful first payment, keeping the subscription in the `incomplete` state until the payment succeeds or the rule expires.
        purchase_order_number:
          type:
            - string
            - 'null'
          example: PO-123
          description: The purchase order number associated with the subscription. It will be added to invoices generated for this subscription.
    SubscriptionsPaginated:
      type: object
      required:
        - subscriptions
        - meta
      properties:
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    WalletRecurringTransactionRule:
      type: object
      description: Object that represents rule for wallet recurring transactions.
      required:
        - created_at
        - expiration_at
        - granted_credits
        - grants_target_top_up
        - ignore_paid_top_up_limits
        - interval
        - invoice_requires_successful_payment
        - lago_id
        - method
        - paid_credits
        - started_at
        - status
        - target_ongoing_balance
        - threshold_credits
        - transaction_metadata
        - transaction_name
        - trigger
      properties:
        lago_id:
          type: string
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: A unique identifier for the recurring transaction rule in the Lago application. Can be used to update a recurring transaction rule.
        trigger:
          type: string
          enum:
            - interval
            - threshold
          description: The trigger. Possible values are `interval` or `threshold`.
          example: interval
        method:
          type: string
          enum:
            - fixed
            - target
          description: The method used for recurring top-up. Possible values are `fixed` or `target`.
          example: target
        interval:
          type: string
          enum:
            - weekly
            - monthly
            - quarterly
            - semiannual
            - yearly
          description: 'The interval used for recurring top-up. It represents the frequency at which automatic top-up occurs. The interval can be one of the following values: `weekly`, `monthly`, `quarterly`, `semiannual` or `yearly`. Required only if trigger is set to `interval`.'
          example: monthly
        status:
          type: string
          enum:
            - active
            - terminated
          description: The status of the recurring transaction rule. Possible values are `active` or `terminated`.
          example: active
        threshold_credits:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: The threshold for recurring top-ups is the value at which an automatic top-up is triggered. For example, if this threshold is set at 10 credits, an automatic top-up will occur whenever the wallet balance falls to or below 10 credits. Required only when trigger is set to `threshold`.
          example: '20.0'
        paid_credits:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: The number of paid credits. Required only if there is no granted credits.
          example: '20.0'
        granted_credits:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: The number of free granted credits. Required only if there is no paid credits.
          example: '10.0'
        grants_target_top_up:
          type:
            - boolean
            - 'null'
          description: Applies only to `target` rules. When `true`, the recurring top-up grants free credits to reach the target ongoing balance instead of creating a paid top-up (and bypasses the paid top-up minimum). When `false`, the gap is filled with a paid top-up. `null` for `fixed` rules. Defaults to `false` for target rules when omitted.
          example: false
        started_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2022-08-08T00:00:00Z'
          description: The effective start date for recurring top-ups. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
        target_ongoing_balance:
          type:
            - string
            - 'null'
          pattern: ^[0-9]+.?[0-9]*$
          description: The target ongoing balance is the value set for the ongoing balance to be reached by the automatic top-up. Required only when trigger is set to `target`.
          example: '200.0'
        created_at:
          type: string
          format: date-time
          example: '2022-04-29T08:59:51Z'
          description: The date of the metadata object creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). The creation_date provides a standardized and internationally recognized timestamp for when the metadata object was created
        expiration_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The expiration date and time for this specific recurring transaction rule. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
          example: '2023-09-30T23:59:59Z'
        invoice_requires_successful_payment:
          type: boolean
          description: A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false.
          example: false
        transaction_metadata:
          type: array
          description: This field allows you to store a list of key-value pairs containing additional information or custom attributes. These key-value pairs will populate the metadata of the wallet transactions triggered by this rule.
          items:
            type: object
            properties:
              key:
                type: string
                description: The unique identifier for the attribute.
              value:
                type: string
                description: The value associated with the key.
          example:
            - key: example_key
              value: example_value
            - key: another_key
              value: another_value
        transaction_name:
          type:
            - string
            - 'null'
          description: The name of the wallet transactions triggered by this rule. It will appear on the invoice as the label for the fee. If not set, the label on the invoice will fallback to either `Prepaid credits - {{wallet_name}}` if the wallet name is set, or `Prepaid credits`.
          example: Tokens for models 'high-fidelity-boost'
        ignore_paid_top_up_limits:
          type: boolean
          description: When true, allows rule to topped up wallet with transactions that exceed the paid top-up limits. Defaults to false.
          example: false
        applied_invoice_custom_sections:
          description: The invoice custom sections applied to invoices generated by this recurring transaction rule.
          type: array
          items:
            $ref: '#/components/schemas/AppliedInvoiceCustomSectionObject'
        payment_method:
          $ref: '#/components/schemas/PaymentMethodReference'
          description: The payment method assigned to this recurring transaction rule for processing top-up payments.
        purchase_order_number:
          type:
            - string
            - 'null'
          example: PO-123
          description: The purchase order number associated with this recurring transaction rule. It will be added to invoices generated for the resulting wallet top-ups. If not set, falls back to the wallet's `purchase_order_number`.
    WalletObject:
      type: object
      required:
        - lago_id
        - lago_customer_id
        - external_customer_id
        - status
        - currency
        - rate_amount
        - credits_balance
        - balance
        - balance_cents
        - consumed_credits
        - created_at
        - ongoing_balance_cents
        - invoice_requires_successful_payment
        - ongoing_usage_balance_cents
        - credits_ongoing_balance
        - credits_ongoing_usage_balance
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the wallet within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the wallet's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_customer_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_customer_id:
          type: string
          description: The customer external unique identifier (provided by your own application)
          example: hooli_1234
        billing_entity_code:
          type: string
          example: default
          description: The code of the billing entity associated with the wallet.
        status:
          type: string
          enum:
            - active
            - terminated
          description: The status of the wallet. Possible values are `active` or `terminated`.
          example: active
        currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of the wallet.
          example: USD
        name:
          type:
            - string
            - 'null'
          description: The name of the wallet.
          example: Prepaid
        code:
          type:
            - string
            - 'null'
          description: The code of the wallet.
          example: prepaid
        priority:
          type: integer
          minimum: 1
          maximum: 50
          description: 'Wallet priority for ordering when a customer has multiple wallets. Allowed values: 1-50, where 1 is highest priority and 50 is lowest. Defaults to 50.'
          example: 50
        rate_amount:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: The rate of conversion between credits and the amount in the specified currency. It indicates the ratio or factor used to convert credits into the corresponding monetary value in the currency of the transaction.
          example: '1.5'
        credits_balance:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: The current wallet balance expressed in credits. This reflects the available balance after all transactions are settled.
          example: '28.0'
        balance_cents:
          type: integer
          description: The current wallet balance expressed in cents. This reflects the available balance after all transactions are settled.
          example: 1000
        consumed_credits:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: The number of consumed credits.
          example: '2.0'
        created_at:
          type: string
          format: date-time
          description: The date of the wallet creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
          example: '2022-04-29T08:59:51Z'
        expiration_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time that determines when the wallet will expire. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
          example: null
        last_balance_sync_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time of the last balance top-up. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
          example: '2022-04-29T08:59:51Z'
        last_consumed_credit_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time of the last credits consumption. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
          example: '2022-04-29T08:59:51Z'
        terminated_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date of terminaison of the wallet. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
          example: '2022-09-14T16:35:31Z'
        invoice_requires_successful_payment:
          type: boolean
          description: A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false.
          example: false
        applies_to:
          type: object
          description: Set wallet limitations to fee types.
          properties:
            fee_types:
              type: array
              items:
                type: string
                enum:
                  - charge
                  - subscription
                  - commitment
              description: An array of fee types to which the wallet is applicable. By specifying the fee types in this field, you can restrict the wallet's usage to specific fee types only.
              example:
                - charge
            billable_metric_codes:
              type: array
              items:
                type: string
              description: An array of billable metric codes to which the wallet is applicable. By specifying the billable metric codes in this field, you can restrict the wallet's usage to specific metrics only.
              example:
                - bm1
        recurring_transaction_rules:
          description: List of recurring transaction rules. Currently, we only allow one recurring rule per wallet.
          type: array
          items:
            $ref: '#/components/schemas/WalletRecurringTransactionRule'
        ongoing_balance_cents:
          type: integer
          description: The ongoing wallet balance expressed in cents. This represents the `balance_cents` minus the `ongoing_usage_balance_cents`, showing the real time balance after accounting for current usage including taxes.
          example: 800
        ongoing_usage_balance_cents:
          type: integer
          description: The ongoing usage balance of the wallet, expressed in cents. This reflects all current usage and draft invoices including taxes.
          example: 200
        credits_ongoing_balance:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: The ongoing wallet balance expressed in credits. This represents the `credits_balance` minus the `credits_ongoing_usage_balance`, showing the real time balance after accounting for current usage including taxes.
          example: '8.0'
        credits_ongoing_usage_balance:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: The ongoing usage balance of the wallet, expressed in credits. This reflects all current usage and draft invoices including taxes.
          example: '2.0'
        paid_top_up_min_amount_cents:
          type:
            - integer
            - 'null'
          description: Minimum amount of cents that can be top-up with a single paid transaction.
          example: 100
        paid_top_up_max_amount_cents:
          type:
            - integer
            - 'null'
          description: Maximum amount of cents that can be top-up with a single paid transaction.
          example: 1000
        applied_invoice_custom_sections:
          description: The invoice custom sections applied to invoices generated by this wallet.
          type: array
          items:
            $ref: '#/components/schemas/AppliedInvoiceCustomSectionObject'
        payment_method:
          $ref: '#/components/schemas/PaymentMethodReference'
          description: The payment method assigned to this wallet for processing top-up payments.
        purchase_order_number:
          type:
            - string
            - 'null'
          example: PO-123
          description: The purchase order number associated with the wallet. It will be added to invoices generated for wallet top-ups, unless a more specific purchase order number is set on the wallet transaction or recurring transaction rule that triggered the top-up.
        metadata:
          $ref: '#/components/schemas/MetadataObject'
    WalletsPaginated:
      type: object
      required:
        - wallets
        - meta
      properties:
        wallets:
          type: array
          items:
            $ref: '#/components/schemas/WalletObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    InvoiceCustomSectionInput:
      type: object
      description: Configuration for invoice custom sections to apply to invoices generated by this resource.
      properties:
        skip_invoice_custom_sections:
          type: boolean
          example: false
          description: Set to `true` to exclude all invoice custom sections from PDF generation for invoices related to this resource. When `true`, `invoice_custom_section_codes` is ignored.
        invoice_custom_section_codes:
          type: array
          items:
            type: string
          description: List of unique codes identifying the invoice custom sections to apply. These override the default invoice custom sections configured at the customer or billing entity level.
          example:
            - eu_bank_details
    WalletCreateInput:
      type: object
      properties:
        wallet:
          type: object
          required:
            - rate_amount
            - currency
            - external_customer_id
          properties:
            name:
              type:
                - string
                - 'null'
              description: The name of the wallet.
              example: Prepaid
            code:
              type:
                - string
                - 'null'
              description: The code of the wallet.
              example: prepaid
            priority:
              type: integer
              minimum: 1
              maximum: 50
              description: 'Wallet priority for ordering when a customer has multiple wallets. Allowed values: 1-50, where 1 is highest priority and 50 is lowest. Defaults to 50.'
              example: 50
            rate_amount:
              type: string
              pattern: ^[0-9]+.?[0-9]*$
              description: The rate of conversion between credits and the amount in the specified currency. It indicates the ratio or factor used to convert credits into the corresponding monetary value in the currency of the transaction.
              example: '1.5'
            currency:
              $ref: '#/components/schemas/Currency'
              description: The currency of the wallet.
              example: USD
            paid_credits:
              type:
                - string
                - 'null'
              pattern: ^[0-9]+.?[0-9]*$
              description: The number of paid credits. Required only if there is no granted credits.
              example: '20.0'
            granted_credits:
              type:
                - string
                - 'null'
              pattern: ^[0-9]+.?[0-9]*$
              description: The number of free granted credits. Required only if there is no paid credits.
              example: '10.0'
            external_customer_id:
              type: string
              description: The customer external unique identifier (provided by your own application)
              example: hooli_1234
            billing_entity_code:
              type: string
              example: default
              description: The code of the billing entity associated with the wallet. If not provided, the customer's billing entity is used.
            expiration_at:
              type:
                - string
                - 'null'
              format: date-time
              description: The date and time that determines when the wallet will expire. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
              example: '2022-07-07T23:59:59Z'
            invoice_requires_successful_payment:
              type: boolean
              description: A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false.
              example: false
            transaction_metadata:
              type:
                - array
                - 'null'
              description: This optional field allows you to store a list of key-value pairs that provide additional information or custom attributes. These key-value pairs will be included in the metadata of wallet transactions generated during the wallet creation process.
              items:
                type: object
                properties:
                  key:
                    type: string
                    description: The unique identifier for the attribute.
                  value:
                    type: string
                    description: The corresponding value for the key.
              example:
                - key: example_key
                  value: example_value
                - key: another_key
                  value: another_value
            transaction_name:
              type:
                - string
                - 'null'
              description: The name of the wallet transactions triggered when creating the wallet. It will appear on the invoice as the label for the fee. If not set, the label on the invoice will fallback to either `Prepaid credits - {{wallet_name}}` if the wallet name is set, or `Prepaid credits`.
              example: Tokens for models 'high-fidelity-boost'
            purchase_order_number:
              type:
                - string
                - 'null'
              example: PO-123
              description: The purchase order number associated with the wallet. It will be added to invoices generated for wallet top-ups, unless a more specific purchase order number is set on the wallet transaction or recurring transaction rule that triggered the top-up.
            applies_to:
              type:
                - object
                - 'null'
              description: Set wallet limitations to fee types.
              properties:
                fee_types:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
                    enum:
                      - charge
                      - subscription
                      - commitment
                  description: An array of fee types to which the wallet is applicable. By specifying the fee types in this field, you can restrict the wallet's usage to specific fee types only.
                  example:
                    - charge
                billable_metric_codes:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
                  description: An array of billable metric codes to which the wallet is applicable. By specifying the billable metric codes in this field, you can restrict the wallet's usage to specific metrics only.
                  example: []
            paid_top_up_min_amount_cents:
              type:
                - integer
                - 'null'
              description: Minimum amount of cents that can be top-up with a single paid transaction.
              example: 100
            paid_top_up_max_amount_cents:
              type:
                - integer
                - 'null'
              description: Maximum amount of cents that can be top-up with a single paid transaction.
              example: 1000
            ignore_paid_top_up_limits_on_creation:
              type:
                - boolean
                - 'null'
              description: If set to true, the wallet will ignore paid top-up limits on creation.
              example: false
            invoice_custom_section:
              $ref: '#/components/schemas/InvoiceCustomSectionInput'
            recurring_transaction_rules:
              type:
                - array
                - 'null'
              description: List of recurring transaction rules. Currently, we only allow one recurring rule per wallet.
              items:
                type: object
                description: Object that represents rule for wallet recurring transactions.
                required:
                  - trigger
                properties:
                  paid_credits:
                    type:
                      - string
                      - 'null'
                    pattern: ^[0-9]+.?[0-9]*$
                    description: The number of paid credits used for recurring top-up.
                    example: '20.0'
                  granted_credits:
                    type:
                      - string
                      - 'null'
                    pattern: ^[0-9]+.?[0-9]*$
                    description: The number of free granted credits used for recurring top-up.
                    example: '10.0'
                  grants_target_top_up:
                    type:
                      - boolean
                      - 'null'
                    description: Applies only to `target` rules. When `true`, the recurring top-up grants free credits to reach the target ongoing balance instead of creating a paid top-up (and bypasses the paid top-up minimum). When `false`, the gap is filled with a paid top-up. `null` for `fixed` rules. Defaults to `false` for target rules when omitted.
                    example: false
                  method:
                    type: string
                    enum:
                      - fixed
                      - target
                    description: The method used for recurring top-up. Possible values are `fixed` or `target`.
                    example: target
                  trigger:
                    type: string
                    enum:
                      - interval
                      - threshold
                    description: The trigger. Possible values are `interval` or `threshold`.
                    example: interval
                  interval:
                    type: string
                    enum:
                      - weekly
                      - monthly
                      - quarterly
                      - semiannual
                      - yearly
                    description: 'The interval used for recurring top-up. It represents the frequency at which automatic top-up occurs. The interval can be one of the following values: `weekly`, `monthly`, `quarterly`, `semiannual` or `yearly`. Required only when trigger is `interval`.'
                    example: monthly
                  started_at:
                    type:
                      - string
                      - 'null'
                    format: date-time
                    example: '2022-08-08T00:00:00Z'
                    description: The effective start date for recurring top-ups. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
                  expiration_at:
                    type:
                      - string
                      - 'null'
                    format: date-time
                    description: The expiration date and time for this specific recurring transaction rule. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
                    example: '2023-09-30T23:59:59Z'
                  threshold_credits:
                    type: string
                    pattern: ^[0-9]+.?[0-9]*$
                    description: The threshold for recurring top-ups is the value at which an automatic top-up is triggered. For example, if this threshold is set at 10 credits, an automatic top-up will occur whenever the wallet balance falls to or below 10 credits. Required only when trigger is set to `threshold`.
                    example: '20.0'
                  target_ongoing_balance:
                    type: string
                    pattern: ^[0-9]+.?[0-9]*$
                    description: The target ongoing balance is the value set for the ongoing balance to be reached by the automatic top-up. Required only when trigger is set to `target`.
                    example: '200.0'
                  invoice_requires_successful_payment:
                    type: boolean
                    description: A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false.
                    example: false
                  transaction_metadata:
                    type: array
                    description: This optional field allows you to store a list of key-value pairs containing additional information or custom attributes. These key-value pairs will populate the metadata of the wallet transactions triggered by this rule.
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          description: The unique identifier for the attribute.
                        value:
                          type: string
                          description: The value associated with the key.
                    example:
                      - key: example_key
                        value: example_value
                      - key: another_key
                        value: another_value
                  transaction_name:
                    type:
                      - string
                      - 'null'
                    description: The name of the wallet transactions triggered by this rule. It will appear on the invoice as the label for the fee. If not set, the label on the invoice will fallback to either `Prepaid credits - {{wallet_name}}` if the wallet name is set, or `Prepaid credits`.
                    example: Tokens for models 'high-fidelity-boost'
                  purchase_order_number:
                    type:
                      - string
                      - 'null'
                    example: PO-123
                    description: The purchase order number associated with this recurring transaction rule. It will be added to invoices generated for the resulting wallet top-ups. If not set, falls back to the wallet's `purchase_order_number`.
                  ignore_paid_top_up_limits:
                    type: boolean
                    description: When true, allows rule to topped up wallet with transactions that exceed the paid top-up limits. Defaults to false.
                    example: false
                  invoice_custom_section:
                    $ref: '#/components/schemas/InvoiceCustomSectionInput'
                  payment_method:
                    $ref: '#/components/schemas/PaymentMethodReference'
                    description: Optional payment method to use for processing recurring top-up payments.
            payment_method:
              $ref: '#/components/schemas/PaymentMethodReference'
              description: Optional payment method to use for processing wallet top-up payments.
            metadata:
              $ref: '#/components/schemas/MetadataInput'
    Wallet:
      type: object
      required:
        - wallet
      properties:
        wallet:
          $ref: '#/components/schemas/WalletObject'
    WalletUpdateInput:
      type: object
      required:
        - wallet
      properties:
        wallet:
          type: object
          properties:
            name:
              type:
                - string
                - 'null'
              description: The name of the wallet.
              example: new_name
            code:
              type:
                - string
                - 'null'
              description: The code of the wallet.
              example: prepaid
            priority:
              type: integer
              minimum: 1
              maximum: 50
              description: 'Wallet priority for ordering when a customer has multiple wallets. Allowed values: 1-50, where 1 is highest priority and 50 is lowest. Defaults to 50.'
              example: 50
            expiration_at:
              type:
                - string
                - 'null'
              format: date-time
              description: The date and time that determines when the wallet will expire. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
              example: '2022-07-07T23:59:59Z'
            invoice_requires_successful_payment:
              type: boolean
              description: A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false.
              example: false
            billing_entity_code:
              type: string
              example: default
              description: The code of the billing entity associated with the wallet.
            purchase_order_number:
              type:
                - string
                - 'null'
              example: PO-123
              description: The purchase order number associated with the wallet. It will be added to invoices generated for wallet top-ups, unless a more specific purchase order number is set on the wallet transaction or recurring transaction rule that triggered the top-up.
            invoice_custom_section:
              $ref: '#/components/schemas/InvoiceCustomSectionInput'
            recurring_transaction_rules:
              type: array
              description: List of recurring transaction rules. Currently, we only allow one recurring rule per wallet.
              required:
                - trigger
              items:
                type: object
                description: Object that represents rule for wallet recurring transactions.
                properties:
                  lago_id:
                    type: string
                    format: uuid
                    example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                    description: A unique identifier for the recurring transaction rule in the Lago application. Can be used to update a recurring transaction rule.
                  trigger:
                    type: string
                    enum:
                      - interval
                      - threshold
                    description: The trigger. Possible values are `interval` or `threshold`.
                    example: interval
                  method:
                    type: string
                    enum:
                      - fixed
                      - target
                    description: The method used for recurring top-up. Possible values are `fixed` or `target`.
                    example: target
                  interval:
                    type: string
                    enum:
                      - weekly
                      - monthly
                      - quarterly
                      - semiannual
                      - yearly
                    description: 'The interval used for recurring top-up. It represents the frequency at which automatic top-up occurs. The interval can be one of the following values: `weekly`, `monthly`, `quarterly`, `semiannual` or `yearly`. Required only when trigger is set to `interval`.'
                    example: monthly
                  threshold_credits:
                    type: string
                    pattern: ^[0-9]+.?[0-9]*$
                    description: The threshold for recurring top-ups is the value at which an automatic top-up is triggered. For example, if this threshold is set at 10 credits, an automatic top-up will occur whenever the wallet balance falls to or below 10 credits. Required only when trigger is set to `threshold`.
                    example: '20.0'
                  paid_credits:
                    type:
                      - string
                      - 'null'
                    pattern: ^[0-9]+.?[0-9]*$
                    description: The number of paid credits. Required only if there is no granted credits.
                    example: '20.0'
                  granted_credits:
                    type:
                      - string
                      - 'null'
                    pattern: ^[0-9]+.?[0-9]*$
                    description: The number of free granted credits. Required only if there is no paid credits.
                    example: '10.0'
                  grants_target_top_up:
                    type:
                      - boolean
                      - 'null'
                    description: Applies only to `target` rules. When `true`, the recurring top-up grants free credits to reach the target ongoing balance instead of creating a paid top-up (and bypasses the paid top-up minimum). When `false`, the gap is filled with a paid top-up. `null` for `fixed` rules. Defaults to `false` for target rules when omitted.
                    example: false
                  started_at:
                    type:
                      - string
                      - 'null'
                    format: date-time
                    example: '2022-08-08T00:00:00Z'
                    description: The effective start date for recurring top-ups. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
                  expiration_at:
                    type:
                      - string
                      - 'null'
                    format: date-time
                    description: The expiration date and time for this specific recurring transaction rule. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
                    example: '2023-09-30T23:59:59Z'
                  target_ongoing_balance:
                    type: string
                    pattern: ^[0-9]+.?[0-9]*$
                    description: The target ongoing balance is the value set for the ongoing balance to be reached by the automatic top-up. Required only when trigger is set to `target`.
                    example: '200.0'
                  invoice_requires_successful_payment:
                    type: boolean
                    description: A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false.
                    example: false
                  transaction_metadata:
                    type: array
                    description: This optional field allows you to store a list of key-value pairs containing additional information or custom attributes. These key-value pairs will populate the metadata of the wallet transactions triggered by this rule.
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          description: The unique identifier for the attribute.
                        value:
                          type: string
                          description: The value associated with the key.
                    example:
                      - key: example_key
                        value: example_value
                      - key: another_key
                        value: another_value
                  transaction_name:
                    type:
                      - string
                      - 'null'
                    description: The name of the wallet transactions triggered by this rule. It will appear on the invoice as the label for the fee. If not set, the label on the invoice will fallback to either `Prepaid credits - {{wallet_name}}` if the wallet name is set, or `Prepaid credits`.
                    example: Tokens for models 'high-fidelity-boost'
                  purchase_order_number:
                    type:
                      - string
                      - 'null'
                    example: PO-123
                    description: The purchase order number associated with this recurring transaction rule. It will be added to invoices generated for the resulting wallet top-ups. If not set, falls back to the wallet's `purchase_order_number`.
                  invoice_custom_section:
                    $ref: '#/components/schemas/InvoiceCustomSectionInput'
                  payment_method:
                    $ref: '#/components/schemas/PaymentMethodReference'
                    description: Optional payment method to use for processing recurring top-up payments.
            payment_method:
              $ref: '#/components/schemas/PaymentMethodReference'
              description: Optional payment method to use for processing wallet top-up payments.
            applies_to:
              type:
                - object
                - 'null'
              description: Set wallet limitations to fee types.
              properties:
                fee_types:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
                    enum:
                      - charge
                      - subscription
                      - commitment
                  description: An array of fee types to which the wallet is applicable. By specifying the fee types in this field, you can restrict the wallet's usage to specific fee types only.
                  example:
                    - charge
                billable_metric_codes:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
                  description: An array of billable metric codes to which the wallet is applicable. By specifying the billable metric codes in this field, you can restrict the wallet's usage to specific metrics only.
                  example: []
            metadata:
              $ref: '#/components/schemas/MetadataInput'
    WalletMetadataResponse:
      type: object
      required:
        - metadata
      properties:
        metadata:
          $ref: '#/components/schemas/MetadataObject'
    AlertThresholdBaseObject:
      type: object
      properties:
        code:
          type:
            - string
            - 'null'
          description: Unique identifier of the usage threshold created by Lago.
          example: warn
        recurring:
          type: boolean
          default: false
          description: This field when set to `true` indicates that the alert will be retrigger when this threshold is reached after the last non-recurring threshold. Only one recurring threshold per alert allowed.
          example: false
    AlertThresholdObject:
      allOf:
        - $ref: '#/components/schemas/AlertThresholdBaseObject'
        - type: object
          required:
            - code
            - value
            - recurring
          properties:
            value:
              type: string
              pattern: ^[0-9]+.?[0-9]*$
              description: A value that should trigger this alert, formatted as a BigDecimal.
              example: '99.0'
    WalletAlertObject:
      type: object
      required:
        - lago_id
        - lago_organization_id
        - external_subscription_id
        - billable_metric
        - alert_type
        - code
        - name
        - previous_value
        - last_processed_at
        - thresholds
        - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the alert, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_organization_id:
          type: string
          format: uuid
          description: Unique identifier of the organization, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_subscription_id:
          type: 'null'
        lago_wallet_id:
          type: string
          description: Unique identifier of the wallet, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        wallet_code:
          type: string
          description: The wallet external unique identifier (provided by your own application).
          example: wallet_code
        billable_metric:
          type: 'null'
        alert_type:
          type: string
          description: The type of alert.
          enum:
            - wallet_balance_amount
            - wallet_credits_balance
            - wallet_ongoing_balance_amount
            - wallet_credits_ongoing_balance
          example: wallet_balance_amount
        code:
          type: string
          description: Unique code used to identify the alert.
          example: wallet_balance_alert
        name:
          type:
            - string
            - 'null'
          description: The name of the alert.
          example: Wallet Balance Alert
        direction:
          type: string
          description: Indicates whether the alert is triggered when the monitored metric goes above or below the threshold.
          enum:
            - increasing
            - decreasing
          example: decreasing
        previous_value:
          type: number
          description: When the system checked if this alert should be triggered, this value was retrieved and checked against the thresholds.
          example: 1000
        last_processed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time in UTC (ISO 8601) when the system checked if this alert should be triggered. Null until it's processed for the first time.
          example: '2025-05-19T10:04:21Z'
        thresholds:
          type: array
          description: Array of thresholds associated with the alert.
          items:
            $ref: '#/components/schemas/AlertThresholdObject'
        created_at:
          type: string
          format: date-time
          description: The date and time in UTC (ISO 8601) when the alert was created.
          example: '2025-03-20T10:00:00Z'
    WalletAlerts:
      type: object
      required:
        - alerts
      properties:
        alerts:
          type: array
          items:
            $ref: '#/components/schemas/WalletAlertObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    AlertThresholdInput:
      allOf:
        - $ref: '#/components/schemas/AlertThresholdBaseObject'
        - type: object
          required:
            - value
          properties:
            value:
              oneOf:
                - type: integer
                - type: string
              description: A value that should trigger this alert. This can be an integer or a string formatted as a BigDecimal.
              example: 99
    AlertBaseInput:
      type: object
      properties:
        code:
          type: string
          description: Unique code used to identify the alert.
          example: storage_threshold_alert
        name:
          type:
            - string
            - 'null'
          description: The name of the alert.
          example: Storage Usage Alert
        thresholds:
          type: array
          description: Array of thresholds associated with the alert.
          items:
            $ref: '#/components/schemas/AlertThresholdInput'
    WalletAlertCreateInput:
      type: object
      required:
        - alert
      properties:
        alert:
          allOf:
            - $ref: '#/components/schemas/AlertBaseInput'
            - type: object
              required:
                - alert_type
                - code
                - thresholds
              properties:
                alert_type:
                  type: string
                  description: The type of alert.
                  enum:
                    - wallet_balance_amount
                    - wallet_credits_balance
                    - wallet_ongoing_balance_amount
                    - wallet_credits_ongoing_balance
                  example: wallet_balance_amount
                code:
                  type: string
                  description: Unique code used to identify the alert.
                  example: wallet_balance_alert
                name:
                  type:
                    - string
                    - 'null'
                  description: The name of the alert.
                  example: Wallet Balance Alert
    WalletAlertBatchCreateInput:
      type: object
      required:
        - alerts
      properties:
        alerts:
          type: array
          description: Array of alerts to create. All alerts are created atomically - if any fail validation, none are created.
          items:
            allOf:
              - $ref: '#/components/schemas/AlertBaseInput'
              - type: object
                required:
                  - alert_type
                  - code
                  - thresholds
                properties:
                  alert_type:
                    type: string
                    description: The type of alert.
                    enum:
                      - wallet_balance_amount
                      - wallet_credits_balance
                      - wallet_ongoing_balance_amount
                      - wallet_credits_ongoing_balance
                    example: wallet_balance_amount
                  code:
                    type: string
                    description: Unique code used to identify the alert.
                    example: wallet_balance_alert
                  name:
                    type:
                      - string
                      - 'null'
                    description: The name of the alert.
                    example: Wallet Balance Alert
    WalletAlert:
      type: object
      required:
        - alert
      properties:
        alert:
          $ref: '#/components/schemas/WalletAlertObject'
    WalletAlertUpdateInput:
      type: object
      required:
        - alert
      properties:
        alert:
          allOf:
            - $ref: '#/components/schemas/AlertBaseInput'
            - type: object
              properties:
                code:
                  type: string
                  description: Unique code used to identify the alert.
                  example: wallet_balance_alert
                name:
                  type:
                    - string
                    - 'null'
                  description: The name of the alert.
                  example: Wallet Balance Alert
    UsagePricingUnitDetailsObject:
      type:
        - object
        - 'null'
      required:
        - amount_cents
        - short_name
        - conversion_rate
      description: Details about the pricing unit used for charge usage.
      properties:
        amount_cents:
          type: integer
          example: 200
          description: The amount in cents in the pricing unit.
        short_name:
          type: string
          example: CR
          description: The short name of the pricing unit.
        conversion_rate:
          type: string
          example: '0.5'
          description: The conversion rate from pricing units to the plan's currency.
    CustomerChargeFiltersUsageObject:
      type: array
      description: Array of filter object, representing multiple dimensions for a charge item.
      required:
        - values
        - units
        - total_aggregated_units
        - events_count
        - 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.
          total_aggregated_units:
            type: string
            pattern: ^[0-9]+.?[0-9]*$
            example: '1.0'
            description: The total number of units consumed by the customer for a specific charge item, aggregated across all usage events.
          amount_cents:
            type: integer
            example: 1000
            description: The amount in cents, tax excluded, 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/PresentationBreakdownsObject'
    CustomerChargeGroupedUsageObject:
      type: array
      description: Array of aggregated fees, grouped by the event properties defined in a `standard` charge model.
      required:
        - amount_cents
        - events_count
        - units
        - total_aggregated_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.
          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.
          total_aggregated_units:
            type: string
            pattern: ^[0-9]+.?[0-9]*$
            example: '1.0'
            description: The total number of units consumed by the customer for a specific charge item, aggregated across all usage events.
          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/PresentationBreakdownsObject'
    CustomerChargeUsageObject:
      type: object
      required:
        - units
        - total_aggregated_units
        - events_count
        - amount_cents
        - amount_currency
        - charge
        - billable_metric
      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.
        total_aggregated_units:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          example: '1.0'
          description: The total number of units consumed by the customer for a specific charge item, aggregated across all usage events.
        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.
        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
                - 'null'
              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/CustomerChargeFiltersUsageObject'
        grouped_usage:
          $ref: '#/components/schemas/CustomerChargeGroupedUsageObject'
        presentation_breakdowns:
          $ref: '#/components/schemas/PresentationBreakdownsObject'
    CustomerUsageObject:
      type: object
      required:
        - from_datetime
        - to_datetime
        - issuing_date
        - amount_cents
        - taxes_amount_cents
        - total_amount_cents
        - charges_usage
      properties:
        from_datetime:
          type: string
          format: date-time
          description: The lower bound of the billing period, expressed in the ISO 8601 datetime format in Coordinated Universal Time (UTC).
          example: '2022-07-01T00:00:00Z'
        to_datetime:
          type: string
          format: date-time
          description: The upper bound of the billing period, expressed in the ISO 8601 datetime format in Coordinated Universal Time (UTC).
          example: '2022-07-31T23:59:59Z'
        issuing_date:
          type: string
          format: date
          description: The date of creation of the invoice.
          example: '2022-08-01'
        lago_invoice_id:
          type:
            - string
            - 'null'
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: A unique identifier associated with the invoice related to this particular usage record.
        currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of the customer's current usage.
          example: EUR
        amount_cents:
          type: integer
          description: The amount in cents, tax excluded.
          example: 123
        taxes_amount_cents:
          type: integer
          description: The tax amount in cents.
          example: 200
        total_amount_cents:
          type: integer
          description: The total amount in cents, tax included.
          example: 123
        charges_usage:
          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'
    CustomerUsage:
      type: object
      required:
        - customer_usage
      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/PresentationBreakdownsObject'
          projected_presentation_breakdowns:
            $ref: '#/components/schemas/PresentationBreakdownsObject'
    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/CustomerProjectedChargeFiltersUsageObject'
          presentation_breakdowns:
            $ref: '#/components/schemas/PresentationBreakdownsObject'
          projected_presentation_breakdowns:
            $ref: '#/components/schemas/PresentationBreakdownsObject'
    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/PresentationBreakdownsObject'
        projected_presentation_breakdowns:
          $ref: '#/components/schemas/PresentationBreakdownsObject'
    CustomerProjectedUsageObject:
      type: object
      required:
        - from_datetime
        - to_datetime
        - issuing_date
        - amount_cents
        - projected_amount_cents
        - taxes_amount_cents
        - total_amount_cents
        - charges_usage
      properties:
        from_datetime:
          type: string
          format: date-time
          description: The lower bound of the billing period, expressed in the ISO 8601 datetime format in Coordinated Universal Time (UTC).
          example: '2022-07-01T00:00:00Z'
        to_datetime:
          type: string
          format: date-time
          description: The upper bound of the billing period, expressed in the ISO 8601 datetime format in Coordinated Universal Time (UTC).
          example: '2022-07-31T23:59:59Z'
        issuing_date:
          type: string
          format: date
          description: The date of creation of the invoice.
          example: '2022-08-01'
        lago_invoice_id:
          type:
            - string
            - 'null'
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: A unique identifier associated with the invoice related to this particular usage record.
        currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of the customer's current usage.
          example: EUR
        amount_cents:
          type: integer
          description: The amount in cents, tax excluded.
          example: 123
        projected_amount_cents:
          type: integer
          description: The projected amount in cents, tax excluded.
          example: 256
        taxes_amount_cents:
          type: integer
          description: The tax amount in cents.
          example: 200
        total_amount_cents:
          type: integer
          description: The total amount in cents, tax included.
          example: 123
        charges_usage:
          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/CustomerProjectedChargeUsageObject'
    CustomerProjectedUsage:
      type: object
      required:
        - customer_projected_usage
      properties:
        customer_projected_usage:
          $ref: '#/components/schemas/CustomerProjectedUsageObject'
    CustomerPastUsage:
      type: object
      required:
        - usage_periods
        - meta
      properties:
        usage_periods:
          type: array
          items:
            $ref: '#/components/schemas/CustomerUsageObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    CustomerCheckoutUrl:
      type: object
      required:
        - lago_customer_id
        - external_customer_id
        - payment_provider
      properties:
        lago_customer_id:
          type: string
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer's record within the Lago system
        external_customer_id:
          type: string
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
          description: The customer external unique identifier (provided by your own application)
        payment_provider:
          type: string
          example: stripe
          description: The Payment Provider name linked to the Customer.
        payment_provider_code:
          type: string
          description: Code of the payment provider
          example: Stripe Prod
        checkout_url:
          type: string
          example: https://foo.bar
          description: The new generated Payment Provider Checkout URL for the Customer.
    PaymentMethodObject:
      type: object
      required:
        - lago_id
        - is_default
        - payment_provider_type
        - provider_method_id
        - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: The unique identifier of the payment method, created by Lago.
          example: 4cf085a7-c196-4f07-a543-97c50ec6e8b2
        is_default:
          type: boolean
          description: Indicates whether this payment method is the default one for the customer.
          example: true
        payment_provider_code:
          type:
            - string
            - 'null'
          description: Code of the payment provider associated with this payment method.
          example: stripe_prod
        payment_provider_name:
          type:
            - string
            - 'null'
          description: Human-readable name of the payment provider.
          example: Stripe
        payment_provider_type:
          type: string
          description: The type of the payment provider.
          enum:
            - adyen
            - cashfree
            - gocardless
            - stripe
            - flutterwave
            - moneyhash
          example: stripe
        provider_method_id:
          type: string
          description: Unique identifier of the payment method within the payment provider.
          example: pm_1N8ZQX2eZvKYlo2CkL9Y8XYZ
        created_at:
          type: string
          format: date-time
          description: Timestamp when the payment method was created in Lago's database.
          example: '2025-01-21T00:10:29Z'
    PaymentMethodsPaginated:
      type: object
      required:
        - payment_methods
        - meta
      properties:
        payment_methods:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethodObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    PaymentMethod:
      type: object
      required:
        - payment_method
      properties:
        payment_method:
          $ref: '#/components/schemas/PaymentMethodObject'
    EventObject:
      type: object
      required:
        - transaction_id
        - lago_customer_id
        - code
        - timestamp
        - lago_subscription_id
        - external_subscription_id
      properties:
        lago_id:
          type:
            - string
            - 'null'
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: Unique identifier assigned to the event within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the event's record within the Lago system. It is an opaque identifier and is not guaranteed to be a UUID; on organizations using the ClickHouse events store it is a composite string.
        transaction_id:
          type: string
          example: transaction_1234567890
          description: This field represents a unique identifier for the event. It is crucial for ensuring idempotency, meaning that each event can be uniquely identified and processed without causing any unintended side effects.
        lago_customer_id:
          type:
            - string
            - 'null'
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer's record within the Lago system
        code:
          type: string
          example: storage
          description: The code that identifies a targeted billable metric. It is essential that this code matches the `code` property of one of your active billable metrics. If the provided code does not correspond to any active billable metric, it will be ignored during the process.
        timestamp:
          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.
        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.
        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.
          properties:
            operation_type:
              type:
                - string
                - 'null'
              description: The `operation_type` field is only necessary when adding or removing a specific unit when the targeted billable metric adopts a `unique_count_agg` aggregation method. In other cases, the `operation_type` field is not required. The valid values for the `operation_type` field are `add` or `remove`, which indicate whether the unit is being added or removed from the unique count aggregation, respectively.
              enum:
                - add
                - remove
          additionalProperties:
            oneOf:
              - type: string
              - type: integer
              - type: number
          example:
            gb: 10
        lago_subscription_id:
          type:
            - string
            - 'null'
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: Unique identifier assigned to the subscription within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the subscription's record within the Lago system
        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.
        created_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2022-04-29T08:59:51Z'
          description: The creation date of the event's record in the Lago application, presented in the ISO 8601 datetime format, specifically in Coordinated Universal Time (UTC). It provides the precise timestamp of when the event's record was created within the Lago application
    EventsPaginated:
      type: object
      required:
        - events
        - meta
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    EventInputObject:
      type: object
      required:
        - transaction_id
        - external_subscription_id
        - code
      properties:
        transaction_id:
          type: string
          example: transaction_1234567890
          description: |
            This field represents a unique identifier for the event.
            It is crucial for ensuring idempotency, meaning that each event can be uniquely identified and processed without causing any unintended side effects.

            WARNING: If the Lago organization is configured to use the new Clickhouse-based event pipeline (designed for high-volume processing), the idempotency logic is handled differently.
            Event uniqueness is maintained with both `transaction_id` and `timestamp` fields.
            If a new event arrives with identical values for these two fields as an existing event, the new one will overwrite the previous event rather than being rejected.
        external_subscription_id:
          type: string
          example: sub_1234567890
          description: The unique identifier of the subscription in your application. This field is mandatory in order to link events to the correct customer subscription.
        code:
          type: string
          example: storage
          description: The code that identifies a targeted billable metric. It is essential that this code matches the `code` property of one of your active billable metrics. If the provided code does not correspond to any active billable metric, it will be ignored during the process.
        timestamp:
          oneOf:
            - type: integer
            - type: string
          example: '1651240791.123'
          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.
        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 usage amount.
        properties:
          type:
            - object
            - 'null'
          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.
          additionalProperties:
            oneOf:
              - type: string
              - type: integer
              - type: number
          example:
            gb: 10
    EventInput:
      type: object
      required:
        - event
      properties:
        event:
          $ref: '#/components/schemas/EventInputObject'
    EventCreated:
      type: object
      required:
        - event
      properties:
        event:
          allOf:
            - $ref: '#/components/schemas/EventObject'
            - type: object
              properties:
                lago_customer_id:
                  type: 'null'
                  description: The value will always be null in this response as the event processing is done asynchronously
                  example: null
    EventBatchInput:
      type: object
      required:
        - events
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventInputObject'
    EventsCreated:
      type: object
      required:
        - events
      properties:
        events:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/EventObject'
              - type: object
                properties:
                  lago_customer_id:
                    type: 'null'
                    description: The value will always be null in this response as the event processing is done asynchronously
                    example: null
    EventEstimateFeesInput:
      type: object
      required:
        - event
      properties:
        event:
          type: object
          required:
            - code
            - external_subscription_id
          properties:
            code:
              type: string
              example: storage
              description: The code that identifies a targeted billable metric. It is essential that this code matches the `code` property of one of your active billable metrics. If the provided code does not correspond to any active billable metric, it will be ignored during the process.
            external_subscription_id:
              type: string
              example: sub_1234567890
              description: The unique identifier of the subscription within your application.
            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.
    Fees:
      type: object
      required:
        - fees
      properties:
        fees:
          type: array
          items:
            $ref: '#/components/schemas/FeeObject'
    EventEstimateInstantFeesInput:
      type: object
      required:
        - event
      properties:
        event:
          type: object
          required:
            - code
            - external_subscription_id
          properties:
            code:
              type: string
              example: storage
              description: The code that identifies a targeted billable metric. It is essential that this code matches the `code` property of one of your active billable metrics. If the provided code does not correspond to any active billable metric, it will be ignored during the process.
            external_subscription_id:
              type: string
              example: sub_1234567890
              description: The unique identifier of the subscription within your application.
            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.
            transaction_id:
              type:
                - string
                - 'null'
              example: transaction_1234567890
              description: This field represents a unique identifier for the event.
    FeeEstimateObject:
      type: object
      required:
        - item
        - amount_cents
        - amount_currency
        - taxes_amount_cents
        - taxes_rate
        - total_amount_cents
        - total_amount_currency
        - pay_in_advance
        - invoiceable
        - units
        - precise_unit_amount
        - payment_status
      properties:
        lago_id:
          type: 'null'
        lago_charge_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the charge that the fee belongs to
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_charge_filter_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Unique identifier assigned to the charge filter that the fee belongs to
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_invoice_id:
          type: 'null'
        lago_true_up_fee_id:
          type: 'null'
        lago_true_up_parent_fee_id:
          type: 'null'
        lago_subscription_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the subscription, created by Lago. This field is specifically displayed when the fee type is charge or subscription.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_customer_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the customer, created by Lago. This field is specifically displayed when the fee type is charge or subscription.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_customer_id:
          type: string
          description: Unique identifier assigned to the customer in your application. This field is specifically displayed when the fee type is charge or subscription.
          example: external_id
        external_subscription_id:
          type: string
          description: Unique identifier assigned to the subscription in your application. This field is specifically displayed when the fee type is charge or subscription.
          example: external_id
        amount_cents:
          type: integer
          description: The cost of this specific fee, excluding any applicable taxes.
          example: 100
        precise_amount:
          type: number
          description: The cost of this specific fee, excluding any applicable taxes, with precision.
          example: 1.0001
        precise_total_amount:
          type: number
          description: The cost of this specific fee, including any applicable taxes, with precision.
          example: 1.0212
        amount_currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of this specific fee. It indicates the monetary unit in which the fee's cost is expressed.
          example: EUR
        taxes_amount_cents:
          type: integer
          description: The cost of the tax associated with this specific fee.
          example: 0
        taxes_precise_amount:
          type: number
          description: The cost of the tax associated with this specific fee, with precision.
          example: 0
        taxes_rate:
          type: number
          description: The tax rate associated with this specific fee.
          example: 20
        units:
          type: string
          description: The number of units used to charge the customer. This field indicates the quantity or count of units consumed or utilized in the context of the charge. It helps in determining the basis for calculating the fee or cost associated with the usage of the service or product provided to the customer.
          example: '0.32'
        description:
          type: 'null'
        precise_unit_amount:
          type: number
          description: The unit amount of the fee per unit, with precision.
          example: 312.5
        precise_coupons_amount_cents:
          type: string
          description: The coupon amount applied to the estimated instant fee. It will always returns 0
          example: '0.0'
        total_amount_cents:
          type: integer
          description: The cost of this specific fee, including any applicable taxes.
          example: 120
        total_amount_currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of this specific fee, including any applicable taxes.
          example: EUR
        events_count:
          type: integer
          description: The number of events that have been sent and used to charge the customer. This field indicates the count or quantity of events that have been processed and considered in the charging process.
          example: 1
        pay_in_advance:
          type: boolean
          description: Flag that indicates whether the fee was paid in advance. It serves as a boolean value, where `true` represents that the fee was paid in advance (straightaway), and `false` indicates that the fee was not paid in arrears (at the end of the period).
          example: true
        invoiceable:
          type: boolean
          description: Flag that indicates whether the fee was included on the invoice. It serves as a boolean value, where `true` represents that the fee was included on the invoice, and `false` indicates that the fee was not included on the invoice.
          example: true
        payment_status:
          type: string
          enum:
            - pending
          description: Indicates the payment status of the fee. It represents the current status of the payment associated with the fee. The value will always `pending`.
          example: pending
        created_at:
          type: 'null'
        succeeded_at:
          type: 'null'
        failed_at:
          type: 'null'
        refunded_at:
          type: 'null'
        event_transaction_id:
          type: string
          description: Unique identifier assigned to the transaction. This field is specifically displayed when the fee type is `charge` and the payment for the fee is made in advance (`pay_in_advance` is set to `true`).
          example: transaction_1234567890
        amount_details:
          type: 'null'
        item:
          type: object
          description: Item attached to the fee
          required:
            - type
            - code
            - name
            - lago_item_id
            - item_type
          properties:
            type:
              type: string
              enum:
                - charge
              description: The fee type. The value will be `charge`.
              example: charge
            code:
              type: string
              description: The code of the fee item. It will be the code of the `billable_metric`.
              example: startup
            name:
              type: string
              description: The name of the fee item. It will be the name of the `billable_metric`.
              example: Startup
            description:
              type: string
              description: The description of the fee item. It will be the name of the `billable_metric`.
              example: Startup description
            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 Fee (SF1)
            filter_invoice_display_name:
              type:
                - string
                - 'null'
              description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the actual charge filter values will be used as the default display name.
              example: AWS eu-east-1
            filters:
              type:
                - object
                - 'null'
              description: Key value list of event properties
              additionalProperties:
                type: array
                items:
                  type: string
            lago_item_id:
              type: string
              example: 1a901a90-1a90-1a90-1a90-1a901a901a90
              description: Unique identifier of the fee item, created by Lago. It will be the identifier of the `billable_metric`.
              format: uuid
            item_type:
              type: string
              enum:
                - BillableMetric
              description: The type of the fee item. Values is `BillableMetric`.
              example: BillableMetric
            grouped_by:
              type: object
              description: Key value list of event properties aggregated by the charge model
              additionalProperties:
                type: string
    FeesEstimate:
      type: object
      required:
        - fees
      properties:
        fees:
          type: array
          items:
            $ref: '#/components/schemas/FeeEstimateObject'
    EventBatchEstimateInstantFeesInput:
      type: object
      required:
        - events
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventEstimateInstantFeesInput'
    Event:
      type: object
      required:
        - event
      properties:
        event:
          $ref: '#/components/schemas/EventObject'
    FeesPaginated:
      type: object
      required:
        - fees
        - meta
      properties:
        fees:
          type: array
          items:
            $ref: '#/components/schemas/FeeObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    Fee:
      type: object
      required:
        - fee
      properties:
        fee:
          $ref: '#/components/schemas/FeeObject'
    FeeUpdateInput:
      type: object
      required:
        - fee
      properties:
        fee:
          type: object
          required:
            - payment_status
          properties:
            payment_status:
              type: string
              enum:
                - pending
                - succeeded
                - failed
                - refunded
              description: The payment status of the fee. Possible values are `pending`, `succeeded`, `failed` or `refunded`.
              example: succeeded
    InvoiceOneOffCreateInput:
      type: object
      required:
        - invoice
      properties:
        invoice:
          type: object
          required:
            - external_customer_id
            - fees
          properties:
            external_customer_id:
              type: string
              description: Unique identifier assigned to the customer in your application.
              example: hooli_1234
            billing_entity_code:
              type: string
              example: default
              description: The code of the billing entity to issue the invoice from. If not provided, the customer's billing entity is used.
            currency:
              $ref: '#/components/schemas/Currency'
              description: The currency of the invoice.
              example: EUR
            fees:
              type: array
              items:
                type: object
                required:
                  - add_on_code
                properties:
                  add_on_code:
                    type: string
                    description: The code of the add-on used as invoice item.
                    example: setup_fee
                  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 Fee (SF1)
                  unit_amount_cents:
                    type:
                      - integer
                      - 'null'
                    description: The amount of the fee per unit, expressed in cents. By default, the amount of the add-on is used.
                    example: 12000
                  units:
                    type:
                      - string
                      - 'null'
                    pattern: ^[0-9]+.?[0-9]*$
                    description: The quantity of units associated with the fee. By default, only 1 unit is added to the invoice.
                    example: '2.5'
                  description:
                    type:
                      - string
                      - 'null'
                    example: The description of the fee line item in the invoice. By default, the description of the add-on is used.
                    description: This is a description
                  from_datetime:
                    type: string
                    description: The lower boundary of the invoice billing interval. The `from_datetime` should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
                    format: date-time
                    example: '2022-08-08T00:00:00Z'
                  to_datetime:
                    type: string
                    description: The upper boundary of the invoice billing interval. The `to_datetime` should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
                    format: date-time
                    example: '2022-08-08T00:00:00Z'
                  tax_codes:
                    $ref: '#/components/schemas/TaxCodes'
                  skip_psp:
                    type:
                      - boolean
                      - 'null'
                    description: If true, the invoice will be created but not sent to the payment provider.
                    example: true
                    default: false
            invoice_custom_section:
              $ref: '#/components/schemas/InvoiceCustomSectionInput'
            payment_method:
              $ref: '#/components/schemas/PaymentMethodReference'
              description: Optional payment method to use for processing the invoice payment.
    BillingPeriodObject:
      type: object
      required:
        - lago_subscription_id
        - external_subscription_id
        - lago_plan_id
        - subscription_from_datetime
        - subscription_to_datetime
        - charges_from_datetime
        - charges_to_datetime
        - invoicing_reason
      properties:
        lago_subscription_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the subscription, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_subscription_id:
          type: string
          description: Unique identifier assigned to the subscription in your application.
          example: external_id
        lago_plan_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the plan, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        subscription_from_datetime:
          type: string
          format: date-time
          description: The beginning date of the subscription billing period. This field indicates the start date of the billing period associated with the subscription fee.
          example: '2022-04-29T08:59:51Z'
        subscription_to_datetime:
          type: string
          format: date-time
          description: The ending date of the subscription billing period. This field indicates the end date of the billing period associated with the subscription fee.
          example: '2022-05-29T08:59:51Z'
        charges_from_datetime:
          type: string
          format: date-time
          description: The beginning date of the period that covers the charge fees. It is applicable only to the `charge` fees attached to the subscription. This field indicates the start date of the billing period or subscription period associated with the fees.
          example: '2022-04-29T08:59:51Z'
        charges_to_datetime:
          type: string
          format: date-time
          description: The ending date of the period that covers the charge fees. It is applicable only to the `charge` fees attached to the subscription. This field indicates the end date of the billing period or subscription period associated with the fees.
          example: '2022-05-29T08:59:51Z'
        invoicing_reason:
          type: string
          enum:
            - subscription_starting
            - subscription_periodic
            - subscription_terminating
            - in_advance_charge
            - in_advance_charge_periodic
            - progressive_billing
          description: The reason explaining why this subscription appears on the invoice.
          example: subscription_starting
    InvoiceObjectExtended:
      allOf:
        - $ref: '#/components/schemas/InvoiceObject'
        - type: object
          properties:
            billing_periods:
              type: array
              items:
                $ref: '#/components/schemas/BillingPeriodObject'
            credits:
              type: array
              items:
                $ref: '#/components/schemas/CreditObject'
            fees:
              type: array
              items:
                $ref: '#/components/schemas/FeeObject'
            subscriptions:
              type: array
              items:
                $ref: '#/components/schemas/SubscriptionObject'
            error_details:
              type: array
              items:
                $ref: '#/components/schemas/ErrorDetailObject'
    Invoice:
      type: object
      required:
        - invoice
      properties:
        invoice:
          $ref: '#/components/schemas/InvoiceObjectExtended'
    InvoiceUpdateInput:
      type: object
      required:
        - invoice
      properties:
        invoice:
          type: object
          properties:
            payment_status:
              type: string
              enum:
                - pending
                - succeeded
                - failed
              description: The payment status of the invoice. Possible values are `pending`, `failed` or `succeeded`.
              example: succeeded
            metadata:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: The metadata object identifier. Only required when updating existing metadata.
                    example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                  key:
                    type: string
                    description: The key in the key-value pair of the metadata.
                    example: digital_ref_id
                  value:
                    type: string
                    maxLength: 140
                    description: The value in the key-value pair of the metadata (140 characters max).
                    example: INV-0123456-98765
    InvoicePaymentUrl:
      type: object
      description: .
      properties:
        invoice_payment_details:
          type: object
          properties:
            lago_customer_id:
              type: string
              example: 1a901a90-1a90-1a90-1a90-1a901a901a90
              description: Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer's record within the Lago system
            lago_invoice_id:
              type: string
              example: 1e501a90-1a90-1a90-1a90-1a901a901a80
              description: Unique identifier assigned to the invoice within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the invoice's record within the Lago system
            external_customer_id:
              type: string
              example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
              description: The customer external unique identifier (provided by your own application)
            payment_provider:
              type: string
              example: stripe
              description: The Payment Provider name linked to the Customer.
            payment_url:
              type: string
              example: https://foo.bar
              description: The generated Payment URL for the Invoice.
    InvoicePreviewInput:
      type: object
      required:
        - customer
      properties:
        customer:
          type: object
          properties:
            address_line1:
              type: string
              example: 5230 Penfield Ave
              description: The first line of the billing address
            address_line2:
              type:
                - string
                - 'null'
              example: null
              description: The second line of the billing address
            city:
              type: string
              example: Woodland Hills
              description: The city of the customer's billing address
            country:
              $ref: '#/components/schemas/Country'
              description: Country code of the customer's billing address. Format must be ISO 3166 (alpha-2)
              example: US
            external_id:
              type: string
              description: Unique identifier assigned to the customer in your application.
              example: hooli_1234
            integration_customers:
              type: array
              items:
                type: object
                required:
                  - integration_type
                  - integration_code
                properties:
                  integration_type:
                    type: string
                    example: anrok
                    description: |-
                      The integration type used for accounting and tax syncs.
                      Accepted values: `anrok`.
                    enum:
                      - anrok
                  integration_code:
                    type: string
                    example: anrok1
                    description: Unique code used to identify an integration connection.
            name:
              type: string
              description: The full name of the customer
              example: Gavin Belson
            currency:
              $ref: '#/components/schemas/Currency'
              description: The currency of the invoice.
              example: EUR
            shipping_address:
              $ref: '#/components/schemas/Address'
            state:
              type: string
              example: CA
              description: The state of the customer's billing address
            tax_identification_number:
              type: string
              description: The tax identification number of the customer
              example: EU123456789
            timezone:
              $ref: '#/components/schemas/Timezone'
              description: The customer's timezone, used for billing purposes in their local time. Overrides the organization's timezone
        plan_code:
          type: string
          description: The code of the plan. It serves as a unique identifier associated with a particular plan. The code is typically used for internal or system-level identification purposes, like assigning a subscription, for instance.
          example: startup
        subscription_at:
          type: string
          description: The anniversary date and time of the initial subscription. This date serves as the basis for billing subscriptions with `anniversary` billing time. The `anniversary_date` should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
          format: date-time
          example: '2022-08-08T00:00:00Z'
        billing_time:
          type: string
          description: The billing time for the subscription, which can be set as either `anniversary` or `calendar`. If not explicitly provided, it will default to `calendar`. The billing time determines the timing of recurring billing cycles for the subscription. By specifying `anniversary`, the billing cycle will be based on the specific date the subscription started (billed fully), while `calendar` sets the billing cycle at the first day of the week/month/year (billed with proration).
          example: anniversary
          enum:
            - calendar
            - anniversary
        coupons:
          type: array
          items:
            type: object
            required:
              - code
            properties:
              name:
                type: string
                description: The name of the coupon.
                example: Startup Deal
              code:
                type: string
                description: Unique code used to identify the coupon.
                example: startup_deal
              coupon_type:
                type: string
                enum:
                  - fixed_amount
                  - percentage
                description: |-
                  The type of the coupon. It can have two possible values: `fixed_amount` or `percentage`.

                  - If set to `fixed_amount`, the coupon represents a fixed amount discount.
                  - If set to `percentage`, the coupon represents a percentage-based discount.
                example: fixed_amount
              amount_cents:
                type:
                  - integer
                  - 'null'
                description: The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type.
                example: 5000
              amount_currency:
                $ref: '#/components/schemas/CurrencyOrNull'
                description: The currency of the coupon. This field is required only for coupon with `fixed_amount` type.
                example: USD
              percentage_rate:
                type:
                  - string
                  - 'null'
                pattern: ^[0-9]+.?[0-9]*$
                description: The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type.
              frequency_duration:
                type:
                  - integer
                  - 'null'
                description: Specifies the number of billing periods to which the coupon applies. This field is required only for coupons with a `recurring` frequency type
                example: 6
        subscriptions:
          type: object
          required:
            - external_ids
          properties:
            external_ids:
              type: array
              items:
                type: string
                description: External identifiers of the customer's subscription.
                example: 441edbe3-9136-4688-a763-e57b6f1dca82
            plan_code:
              type: string
              description: The code of the plan. It serves as a unique identifier associated with the new plan to which the customer is upgrading or downgrading.
              example: new_code
            terminated_at:
              type: string
              description: The date and time when the subscription is terminated. It should defined in the future.
              format: date-time
              example: '2022-08-08T00:00:00Z'
        billing_entity_code:
          type: string
          description: The code of the billing entity to which will be associated a customer if the external_id is not provided. If billing_entity_code is not provided, default billing_entity of organization will be used.
          example: acme_corp
    InvoiceVoidInput:
      type: object
      properties:
        generate_credit_note:
          type: boolean
          description: Set to `true` to force voiding the invoice and generate a credit note.
          example: true
        refund_amount:
          type: integer
          description: Portion of the invoice amount (in cents) to be refunded to the customer in the generated credit note.
          example: 2000
          minimum: 0
        credit_amount:
          type: integer
          description: Portion of the invoice amount (in cents) to be credited to the customer's balance in the generated credit note.
          example: 1150
          minimum: 0
      required: []
      description: Parameters available when voiding an invoice that optionally generate credit notes.
    OrganizationBillingConfiguration:
      type: object
      description: The custom billing settings for your organization.
      properties:
        invoice_footer:
          type:
            - string
            - 'null'
          example: This is my customer footer
          description: The customer invoice message that appears at the bottom of each billing documents.
        invoice_grace_period:
          type: integer
          example: 3
          description: The grace period, expressed in days, for finalizing the invoice. This period refers to the additional time granted to your customers beyond the invoice due date to adjust usage and line items. Can be overwritten by the customer's grace period.
        document_locale:
          type: string
          example: en
          description: The locale of the billing documents, expressed in the ISO 639-1 format. This field indicates the language or regional variant used for the documents content issued or the embeddable customer portal.
    OrganizationUpdateInput:
      type: object
      required:
        - organization
      properties:
        organization:
          type: object
          properties:
            webhook_url:
              type:
                - string
                - 'null'
              example: https://webhook.brex.com
              description: The URL of your newest updated webhook endpoint. This URL allows your organization to receive important messages, notifications, or data from the Lago system. By configuring your webhook endpoint to this URL, you can ensure that your organization stays informed and receives relevant information in a timely manner.
            country:
              $ref: '#/components/schemas/CountryOrNull'
              description: The country of your organization.
              example: US
            default_currency:
              $ref: '#/components/schemas/Currency'
              description: The default currency of an organization.
              example: USD
            address_line1:
              type:
                - string
                - 'null'
              example: 100 Brex Street
              description: The first line of your organization's billing address.
            address_line2:
              type:
                - string
                - 'null'
              example: null
              description: The second line of your organization's billing address.
            state:
              type:
                - string
                - 'null'
              example: NYC
              description: The state of your organization's billing address.
            zipcode:
              type:
                - string
                - 'null'
              example: '10000'
              description: The zipcode of your organization's billing address.
            email:
              type:
                - string
                - 'null'
              format: email
              example: brex@brex.com
              description: The email address of your organization used to bill your customers.
            city:
              type:
                - string
                - 'null'
              example: New York
              description: The city of your organization's billing address.
            legal_name:
              type:
                - string
                - 'null'
              example: null
              description: The legal name of your organization.
            legal_number:
              type:
                - string
                - 'null'
              example: null
              description: The legal number of your organization.
            document_numbering:
              type: string
              enum:
                - per_customer
                - per_organization
              example: per_customer
              description: |-
                This parameter configures the method of incrementing invoice numbers for your customers.

                - `per_customer`: Invoice numbers are incremented individually for each customer. This means every customer will have their own unique sequence of invoice numbers, separate from other customers. It ensures that each customer's invoice numbers follow a distinct and isolated numbering pattern.
                - `per_organization`: Invoice number incrementation is made across your entire organization. Rather than individual sequences for each customer, all invoices within the organization follow a single, unified numbering system. This creates a continuous and organization-wide sequence for all invoice numbers. Invoices are incremented per month (dynamic value used is YYYYMM), and invoice numbers are reset at the end of each month.

                The default value for `document_numbering` is set to `per_customer`, meaning that, unless changed, invoice numbers will increment uniquely for each customer.
            document_number_prefix:
              type: string
              example: ORG-1234
              description: Sets the prefix for invoices and credit notes. Default is the first three letters of your organization name plus the last four digits of your organization ID. Customizable within 1-10 characters, and automatically capitalized by Lago.
            net_payment_term:
              type: integer
              example: 30
              description: The net payment term, expressed in days, specifies the duration within which a customer is expected to remit payment after the invoice is finalized.
            tax_identification_number:
              type:
                - string
                - 'null'
              example: US123456789
              description: The tax identification number of your organization.
            timezone:
              $ref: '#/components/schemas/Timezone'
              description: Your organization's timezone, used for billing purposes in your own local time. Can be overwritten by the customer's timezone.
              example: America/New_York
            email_settings:
              type: array
              description: Represents the email settings of the organization. It allows you to define which documents are sent by email. The field value determines the types of documents that trigger email notifications. Possible values for are `invoice.finalized` and `credit_note.created`. By configuring this field, you can specify whether invoices, credit notes, or both should be sent to recipients via email.
              example:
                - invoice.finalized
                - credit_note.created
              items:
                type: string
                enum:
                  - invoice.finalized
                  - credit_note.created
            billing_configuration:
              $ref: '#/components/schemas/OrganizationBillingConfiguration'
            finalize_zero_amount_invoice:
              type: boolean
              example: false
              description: Determines whether invoices with a zero total amount should be finalized. If set to true, zero amount invoices will be finalized. If set to false, zero amount invoices will not be finalized.
    OrganizationObject:
      type: object
      required:
        - lago_id
        - name
        - created_at
        - document_numbering
        - document_number_prefix
        - email_settings
        - billing_configuration
      properties:
        lago_id:
          type: string
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: Unique identifier assigned to the organization within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the organization's record within the Lago system
        name:
          type: string
          example: Name1
          description: The name of your organization.
        created_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2022-05-02T13:04:09Z'
          description: The date of creation of your organization, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
        webhook_url:
          type:
            - string
            - 'null'
          example: https://webhook.brex.com
          description: The URL of your newest updated webhook endpoint. This URL allows your organization to receive important messages, notifications, or data from the Lago system. By configuring your webhook endpoint to this URL, you can ensure that your organization stays informed and receives relevant information in a timely manner.
        webhook_urls:
          type:
            - array
            - 'null'
          items:
            type: string
          example:
            - https://webhook.brex.com
            - https://webhook2.brex.com
          description: The array containing your webhooks URLs.
        country:
          $ref: '#/components/schemas/CountryOrNull'
          description: The country of your organization.
          example: US
        default_currency:
          $ref: '#/components/schemas/Currency'
          description: The default currency of an organization.
          example: USD
        address_line1:
          type:
            - string
            - 'null'
          example: 100 Brex Street
          description: The first line of your organization's billing address.
        address_line2:
          type:
            - string
            - 'null'
          example: null
          description: The second line of your organization's billing address.
        state:
          type:
            - string
            - 'null'
          example: NYC
          description: The state of your organization's billing address.
        zipcode:
          type:
            - string
            - 'null'
          example: '10000'
          description: The zipcode of your organization's billing address.
        email:
          type:
            - string
            - 'null'
          format: email
          example: brex@brex.com
          description: The email address of your organization used to bill your customers.
        city:
          type:
            - string
            - 'null'
          example: New York
          description: The city of your organization's billing address.
        legal_name:
          type:
            - string
            - 'null'
          example: null
          description: The legal name of your organization.
        legal_number:
          type:
            - string
            - 'null'
          example: null
          description: The legal number of your organization.
        document_numbering:
          type: string
          enum:
            - per_customer
            - per_organization
          example: per_customer
          description: |-
            This parameter configures the method of incrementing invoice numbers for your customers.

            - `per_customer`: Invoice numbers are incremented individually for each customer. This means every customer will have their own unique sequence of invoice numbers, separate from other customers. It ensures that each customer's invoice numbers follow a distinct and isolated numbering pattern.
            - `per_organization`: Invoice number incrementation is made across your entire organization. Rather than individual sequences for each customer, all invoices within the organization follow a single, unified numbering system. This creates a continuous and organization-wide sequence for all invoice numbers. Invoices are incremented per month (dynamic value used is YYYYMM), and invoice numbers are reset at the end of each month.

            The default value for `document_numbering` is set to `per_customer`, meaning that, unless changed, invoice numbers will increment uniquely for each customer.
        document_number_prefix:
          type: string
          example: ORG-1234
          description: Sets the prefix for invoices and credit notes. Default is the first three letters of your organization name plus the last four digits of your organization ID. Customizable within 1-10 characters, and automatically capitalized by Lago.
        net_payment_term:
          type: integer
          example: 30
          description: The net payment term, expressed in days, specifies the duration within which a customer is expected to remit payment after the invoice is finalized.
        tax_identification_number:
          type:
            - string
            - 'null'
          example: US123456789
          description: The tax identification number of your organization.
        timezone:
          $ref: '#/components/schemas/Timezone'
          description: Your organization's timezone, used for billing purposes in your own local time. Can be overwritten by the customer's timezone.
          example: America/New_York
        billing_configuration:
          $ref: '#/components/schemas/OrganizationBillingConfiguration'
        taxes:
          type: array
          description: List of default organization taxes
          items:
            $ref: '#/components/schemas/TaxObject'
        finalize_zero_amount_invoice:
          type: boolean
          example: false
          description: Indicates whether invoices with a zero total amount should be finalized. If set to true, zero amount invoices will be finalized. If set to false, zero amount invoices will not be finalized.
        events_store:
          type: string
          enum:
            - clickhouse
            - postgres
          example: clickhouse
    Organization:
      type: object
      required:
        - organization
      properties:
        organization:
          $ref: '#/components/schemas/OrganizationObject'
    PaymentReceiptObject:
      type: object
      required:
        - lago_id
        - created_at
        - number
        - payment
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the payment receipt, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        created_at:
          type: string
          format: date-time
          description: The date and time when the payment receipt was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the payment receipt was initially created.
          example: '2022-04-29T08:59:51Z'
        number:
          type: string
          description: The unique number assigned to the payment receipt.
          example: LAG-1234-001-002
        payment:
          $ref: '#/components/schemas/PaymentObject'
    PaymentReceiptsPaginated:
      type: object
      required:
        - payment_receipts
        - meta
      properties:
        payment_receipts:
          type: array
          items:
            $ref: '#/components/schemas/PaymentReceiptObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    PaymentReceipt:
      type: object
      required:
        - payment_receipt
      properties:
        payment_receipt:
          $ref: '#/components/schemas/PaymentReceiptObject'
    PaymentRequestCreateInput:
      type: object
      required:
        - payment_request
      properties:
        payment_request:
          type: object
          required:
            - email
            - external_customer_id
            - lago_invoice_ids
          properties:
            external_customer_id:
              type: string
              example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
              description: The customer external unique identifier (provided by your own application)
            email:
              type: string
              format: email
              example: dinesh@piedpiper.test
              description: The customer's email address used for sending dunning notifications
            lago_invoice_ids:
              type: array
              description: A list of Lago IDs for the customer's overdue invoices to start the dunning process
              items:
                type: string
                example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                description: Unique identifier assigned to the invoice within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the invoice's record within the Lago system.
            payment_method:
              $ref: '#/components/schemas/PaymentMethodReference'
              description: Optional payment method to use for processing the payment request.
    PaymentRequest:
      type: object
      required:
        - payment_request
      properties:
        payment_request:
          $ref: '#/components/schemas/PaymentRequestObject'
    PaymentCreateInput:
      type: object
      required:
        - payment
      properties:
        payment:
          type: object
          required:
            - invoice_id
            - amount_cents
            - reference
          properties:
            invoice_id:
              type: string
              example: 486b147a-02a1-4ccf-8603-f3541fc25e7a
              description: Unique identifier assigned to the invoice
            amount_cents:
              type: integer
              example: 100
              description: The payment amount in cents
            reference:
              type: string
              example: ref1
              description: Reference for the payment
            paid_at:
              type: string
              format: date
              example: '2025-02-20'
              description: The date the payment was made
    Payment:
      type: object
      required:
        - payment
      properties:
        payment:
          $ref: '#/components/schemas/PaymentObject'
    MinimumCommitmentObject:
      type:
        - object
        - 'null'
      required:
        - lago_id
        - amount_cents
        - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the minimum commitment, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        plan_code:
          type: string
          example: premium
          description: The unique code representing the plan to be attached to the customer.
        amount_cents:
          type: integer
          description: The amount of the minimum commitment in cents.
          example: 100000
        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 default name will be used as the display name.
          example: Minimum Commitment (C1)
        interval:
          type: string
          description: 'The interval used for recurring billing. It represents the frequency at which subscription billing occurs. The interval can be one of the following values: `yearly`, `semiannual`, `quarterly`, `monthly` or `weekly`.'
          enum:
            - weekly
            - monthly
            - quarterly
            - semiannual
            - yearly
          example: monthly
        created_at:
          type: string
          format: date-time
          description: The date and time when the minimum commitment was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the minimum commitment was initially created.
          example: '2022-04-29T08:59:51Z'
        updated_at:
          type: string
          format: date-time
          description: The date and time when the minimum commitment was updated. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the minimum commitment was initially created.
          example: '2022-04-29T08:59:51Z'
        taxes:
          type: array
          description: All taxes applied to the minimum commitment.
          items:
            $ref: '#/components/schemas/TaxObject'
    ChargeModelEnum:
      type: string
      description: |
        Specifies the pricing model used for the calculation of the final fee. It can be any of the following values:
          - [`dynamic`](https://docs.getlago.com/guide/plans/charges/charge-models/dynamic)
          - [`graduated_percentage`](https://docs.getlago.com/guide/plans/charges/charge-models/graduated-percentage)
          - [`graduated`](https://docs.getlago.com/guide/plans/charges/charge-models/graduated)
          - [`package`](https://docs.getlago.com/guide/plans/charges/charge-models/package)
          - [`percentage`](https://docs.getlago.com/guide/plans/charges/charge-models/percentage)
          - [`standard`](https://docs.getlago.com/guide/plans/charges/charge-models/standard)
          - [`volume`](https://docs.getlago.com/guide/plans/charges/charge-models/volume)
      enum:
        - dynamic
        - graduated
        - graduated_percentage
        - package
        - percentage
        - standard
        - volume
    ChargeProperties:
      type: object
      properties:
        grouped_by:
          type: array
          description: |-
            **Deprecated.** Replaced by `pricing_group_keys`.
            The list of event properties that are used to group the events on the invoice for a `standard` charge model.
          items:
            type: string
          example:
            - agent_name
          deprecated: true
        pricing_group_keys:
          type: array
          description: The list of event properties that are used to group the events on the invoice.
          items:
            type: string
          example:
            - agent_name
        graduated_ranges:
          type: array
          description: Graduated ranges, sorted from bottom to top tiers, used for a `graduated` charge model.
          items:
            type: object
            required:
              - from_value
              - to_value
              - flat_amount
              - per_unit_amount
            properties:
              from_value:
                type: integer
                description: Specifies the lower value of a tier for a `graduated` charge model. It must be either 0 or the previous range's `to_value + 1` to maintain the proper sequence of values.
                example: 0
              to_value:
                type:
                  - integer
                  - 'null'
                description: |-
                  Specifies the highest value of a tier for a `graduated` charge model.
                  - This value must be higher than the from_value of the same tier.
                  - This value must be null for the last tier.
                example: 10
              flat_amount:
                type: string
                pattern: ^[0-9]+.?[0-9]*$
                description: The flat amount for a whole tier, excluding tax, for a `graduated` charge model. It is expressed as a decimal value.
                example: '10'
              per_unit_amount:
                type: string
                pattern: ^[0-9]+.?[0-9]*$
                description: The unit price, excluding tax, for a specific tier of a `graduated` charge model. It is expressed as a decimal value.
                example: '0.5'
        graduated_percentage_ranges:
          type: array
          description: Graduated percentage ranges, sorted from bottom to top tiers, used for a `graduated_percentage` charge model.
          items:
            type: object
            required:
              - from_value
              - to_value
              - rate
              - flat_amount
            properties:
              from_value:
                type: integer
                description: Specifies the lower value of a tier for a `graduated_percentage` charge model. It must be either 0 or the previous range's `to_value + 1` to maintain the proper sequence of values.
                example: 0
              to_value:
                type:
                  - integer
                  - 'null'
                description: |-
                  Specifies the highest value of a tier for a `graduated_percentage` charge model.
                  - This value must be higher than the from_value of the same tier.
                  - This value must be null for the last tier.
                example: 10
              rate:
                type: string
                format: ^[0-9]+.?[0-9]*$
                description: The percentage rate that is applied to the amount of each transaction in the tier for a `graduated_percentage` charge model. It is expressed as a decimal value.
                example: '1'
              flat_amount:
                type: string
                format: ^[0-9]+.?[0-9]*$
                description: The flat amount for a whole tier, excluding tax, for a `graduated_percentage` charge model. It is expressed as a decimal value.
                example: '10'
        amount:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: |-
            - The unit price, excluding tax, for a `standard` charge model. It is expressed as a decimal value.
            - The amount, excluding tax, for a complete set of units in a `package` charge model. It is expressed as a decimal value.
          example: '30'
        free_units:
          type: integer
          description: The quantity of units that are provided free of charge for each billing period in a `package` charge model. This field specifies the number of units that customers can use without incurring any additional cost during each billing cycle.
          example: 100
        package_size:
          type: integer
          description: The quantity of units included in each pack or set for a `package` charge model. It indicates the number of units that are bundled together as a single package or set within the pricing structure.
          example: 1000
        rate:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: The percentage rate that is applied to the amount of each transaction for a `percentage` charge model. It is expressed as a decimal value.
          example: '1'
        fixed_amount:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: The fixed fee that is applied to each transaction for a `percentage` charge model. It is expressed as a decimal value.
          example: '0.5'
        free_units_per_events:
          type:
            - integer
            - 'null'
          description: The count of transactions that are not impacted by the `percentage` rate and fixed fee in a percentage charge model. This field indicates the number of transactions that are exempt from the calculation of charges based on the specified percentage rate and fixed fee.
          example: 5
        free_units_per_total_aggregation:
          type:
            - string
            - 'null'
          pattern: ^[0-9]+.?[0-9]*$
          description: The transaction amount that is not impacted by the `percentage` rate and fixed fee in a percentage charge model. This field indicates the portion of the transaction amount that is exempt from the calculation of charges based on the specified percentage rate and fixed fee.
          example: '500'
        per_transaction_max_amount:
          type:
            - string
            - 'null'
          format: ^[0-9]+.?[0-9]*$
          description: Specifies the maximum allowable spending for a single transaction. Working as a transaction cap.
          example: '3.75'
        per_transaction_min_amount:
          type:
            - string
            - 'null'
          format: ^[0-9]+.?[0-9]*$
          description: Specifies the minimum allowable spending for a single transaction. Working as a transaction floor.
          example: '1.75'
        volume_ranges:
          type: array
          description: Volume ranges, sorted from bottom to top tiers, used for a `volume` charge model.
          items:
            type: object
            required:
              - from_value
              - to_value
              - flat_amount
              - per_unit_amount
            properties:
              from_value:
                type: integer
                description: Specifies the lower value of a tier for a `volume` charge model. It must be either 0 or the previous range's `to_value + 1` to maintain the proper sequence of values.
                example: 0
              to_value:
                type:
                  - integer
                  - 'null'
                description: |-
                  Specifies the highest value of a tier for a `volume` charge model.
                  - This value must be higher than the `from_value` of the same tier.
                  - This value must be `null` for the last tier.
                example: 10
              flat_amount:
                type: string
                pattern: ^[0-9]+.?[0-9]*$
                description: The flat amount for a whole tier, excluding tax, for a `volume` charge model. It is expressed as a decimal value.
                example: '10'
              per_unit_amount:
                type: string
                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.
      required:
        - invoice_display_name
        - properties
        - values
      properties:
        invoice_display_name:
          type:
            - string
            - 'null'
          description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the values of the filter will be used as the default display name.
          example: AWS
        properties:
          $ref: '#/components/schemas/ChargeProperties'
          description: List of all thresholds utilized for calculating the charge.
        values:
          type: object
          description: List of possible filter values. The key and values must match one of the billable metric filters.
          additionalProperties:
            type: array
            items:
              type: string
          example:
            region:
              - us-east-1
    ChargeObject:
      type: object
      required:
        - lago_id
        - lago_billable_metric_id
        - billable_metric_code
        - created_at
        - charge_model
        - invoiceable
        - regroup_paid_fees
        - pay_in_advance
        - prorated
        - min_amount_cents
        - properties
        - filters
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of charge, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_billable_metric_id:
          type: string
          format: uuid
          description: Unique identifier of the billable metric created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        code:
          type:
            - string
            - 'null'
          description: Unique code identifying the charge within the plan.
          example: api_requests_charge
        billable_metric_code:
          type: string
          description: Unique code identifying a billable metric.
          example: requests
        invoice_display_name:
          type:
            - string
            - 'null'
          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
        created_at:
          type: string
          format: date-time
          description: The date and time when the charge was created. It is expressed in UTC format according to the ISO 8601 datetime standard.
          example: '2022-09-14T16:35:31Z'
        charge_model:
          $ref: '#/components/schemas/ChargeModelEnum'
        pay_in_advance:
          type: boolean
          description: This field determines the billing timing for this specific usage-based charge. When set to `true`, the charge is due and invoiced immediately. Conversely, when set to `false`, the charge is due and invoiced at the end of each billing period.
          example: true
        invoiceable:
          type: boolean
          description: This field specifies whether the charge should be included in a proper invoice. If set to `false`, no invoice will be issued for this charge. You can only set it to `false` when `pay_in_advance` is `true`.
          example: true
        regroup_paid_fees:
          type:
            - string
            - 'null'
          enum:
            - null
            - invoice
          description: |-
            This setting can only be configured if `pay_in_advance` is `true` and `invoiceable` is `false`.
            This field determines whether and when the charge fee should be included in
            the invoice. If `null`, no invoice will be issued for this charge fee.
            If `invoice`, an invoice will be generated at the end of the period,
            consolidating all charge fees with a succeeded payment status.
          example: invoice
        prorated:
          type: boolean
          example: false
          description: |-
            Specifies whether a charge is prorated based on the remaining number of days in the billing period or billed fully.

            - If set to `true`, the charge is prorated based on the remaining days in the current billing period.
            - If set to `false`, the charge is billed in full.
            - If not defined in the request, default value is `false`.
        min_amount_cents:
          type: integer
          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/ChargeObjectProperties'
          description: List of all thresholds utilized for calculating the charge.
        filters:
          type: array
          description: List of filters used to apply differentiated pricing based on additional event properties.
          items:
            $ref: '#/components/schemas/ChargeFilterObject'
        taxes:
          type: array
          description: All taxes applied to the charge.
          items:
            $ref: '#/components/schemas/TaxObject'
        applied_pricing_unit:
          type:
            - object
            - 'null'
          required:
            - code
            - conversion_rate
          description: The pricing unit applied to the charge.
          properties:
            code:
              type: string
              description: The code of the pricing unit.
              example: unit_code
            conversion_rate:
              type: string
              description: The conversion rate from pricing units to the plan's currency.
              example: '0.5'
        accepts_target_wallet:
          type:
            - boolean
            - 'null'
          description: Specifies whether the charge accepts a target wallet for prepaid credits deduction.
          example: false
        lago_parent_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Unique identifier of the parent charge (if this is an override).
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
    FixedChargeProperties:
      type: object
      properties:
        amount:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: |-
            - The unit price, excluding tax, for a `standard` charge model. It is expressed as a decimal value.
            - The amount, excluding tax, for a complete set of units in a `package` charge model. It is expressed as a decimal value.
          example: '30'
        graduated_ranges:
          type: array
          description: Graduated ranges, sorted from bottom to top tiers, used for a `graduated` charge model.
          items:
            type: object
            required:
              - from_value
              - to_value
              - flat_amount
              - per_unit_amount
            properties:
              from_value:
                type: integer
                description: Specifies the lower value of a tier for a `graduated` charge model. It must be either 0 or the previous range's `to_value + 1` to maintain the proper sequence of values.
                example: 0
              to_value:
                type:
                  - integer
                  - 'null'
                description: |-
                  Specifies the highest value of a tier for a `graduated` charge model.
                  - This value must be higher than the from_value of the same tier.
                  - This value must be null for the last tier.
                example: 10
              flat_amount:
                type: string
                pattern: ^[0-9]+.?[0-9]*$
                description: The flat amount for a whole tier, excluding tax, for a `graduated` charge model. It is expressed as a decimal value.
                example: '10'
              per_unit_amount:
                type: string
                pattern: ^[0-9]+.?[0-9]*$
                description: The unit price, excluding tax, for a specific tier of a `graduated` charge model. It is expressed as a decimal value.
                example: '0.5'
        volume_ranges:
          type: array
          description: Volume ranges, sorted from bottom to top tiers, used for a `volume` charge model.
          items:
            type: object
            required:
              - from_value
              - to_value
              - flat_amount
              - per_unit_amount
            properties:
              from_value:
                type: integer
                description: Specifies the lower value of a tier for a `volume` charge model. It must be either 0 or the previous range's `to_value + 1` to maintain the proper sequence of values.
                example: 0
              to_value:
                type:
                  - integer
                  - 'null'
                description: |-
                  Specifies the highest value of a tier for a `volume` charge model.
                  - This value must be higher than the `from_value` of the same tier.
                  - This value must be `null` for the last tier.
                example: 10
              flat_amount:
                type: string
                pattern: ^[0-9]+.?[0-9]*$
                description: The flat amount for a whole tier, excluding tax, for a `volume` charge model. It is expressed as a decimal value.
                example: '10'
              per_unit_amount:
                type: string
                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'
    FixedChargeObject:
      type: object
      required:
        - lago_id
        - lago_add_on_id
        - code
        - invoice_display_name
        - add_on_code
        - created_at
        - charge_model
        - pay_in_advance
        - prorated
        - properties
        - units
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the fixed charge, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_add_on_id:
          type: string
          format: uuid
          description: Unique identifier of the add-on associated with this fixed charge.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        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 fee
        add_on_code:
          type: string
          description: Unique code used to identify the add-on.
          example: setup_fee
        created_at:
          type: string
          format: date-time
          description: The date and time when the fixed charge was created. It is expressed in UTC format according to the ISO 8601 datetime standard.
          example: '2023-06-27T19:43:42Z'
        code:
          type: string
          description: Unique code for the fixed charge.
          example: setup_fee
        charge_model:
          type: string
          enum:
            - standard
            - graduated
            - volume
          description: The charge model for the fixed charge. Only `standard`, `graduated`, and `volume` models are supported for fixed charges.
          example: standard
        pay_in_advance:
          type: boolean
          description: This field determines the billing timing for this fixed charge. When set to `true`, the charge is due and invoiced immediately. Conversely, when set to false, the charge is due and invoiced at the end of each billing period.
          example: false
        prorated:
          type: boolean
          description: |
            Specifies whether a fixed charge is prorated based on the remaining number of days in the billing period or billed fully.

            - If set to `true`, the charge is prorated based on the remaining days in the current billing period.
            - If set to `false`, the charge is billed in full.
            - If not defined in the request, default value is `false`.
          example: false
        properties:
          $ref: '#/components/schemas/FixedChargeProperties'
          description: List of all thresholds utilized for calculating the fixed charge.
        units:
          type: number
          description: |-
            The number of units for the fixed charge.

            When retrieved through a subscription-scoped endpoint (e.g. `GET /subscriptions/{external_id}/fixed_charges`), this reflects the per-subscription unit override when one exists, and falls back to the plan-level units otherwise. Plan-scoped endpoints always return the plan-level units.
          example: 1
        lago_parent_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Unique identifier of the parent fixed charge (for plan versions).
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        taxes:
          type: array
          description: List of taxes applied to the fixed charge.
          items:
            $ref: '#/components/schemas/TaxObject'
    PlanEntitlementPrivilegeObject:
      allOf:
        - $ref: '#/components/schemas/FeaturePrivilegeObject'
        - type: object
          required:
            - value
          properties:
            value:
              oneOf:
                - type: integer
                  description: Value for integer type privileges
                - type: boolean
                  description: Value for boolean type privileges
                - type: string
                  description: Value for string or select type privileges
              example: 10
              description: Value assigned to this privilege in the entitlement. Type depends on the privilege's value_type.
    PlanEntitlementObject:
      type: object
      required:
        - code
        - name
        - description
        - privileges
      properties:
        code:
          type: string
          example: seats
          description: Unique code used to identify the feature. Max 255 characters.
        name:
          type:
            - string
            - 'null'
          example: Number of seats
          description: Name of the feature. Max 255 characters.
        description:
          type:
            - string
            - 'null'
          example: Number of users of the account
          description: Description of the feature. Max 600 characters.
        privileges:
          type: array
          items:
            $ref: '#/components/schemas/PlanEntitlementPrivilegeObject'
          example:
            - code: max
              name: Maximum
              value_type: integer
              config: {}
              value: 10
            - code: max_admins
              name: Max Admins
              value_type: integer
              config: {}
              value: 5
            - code: root
              name: Allow root user
              value_type: boolean
              config: {}
              value: true
            - code: provider
              name: SSO Provider
              value_type: select
              value: google
              config:
                select_options:
                  - google
                  - okta
          description: Privileges associated with this feature. Each privilege must have a value assigned.
    PlanEntitlement:
      type: object
      required:
        - entitlement
      properties:
        entitlement:
          $ref: '#/components/schemas/PlanEntitlementObject'
    PlanObject:
      type: object
      required:
        - lago_id
        - name
        - created_at
        - code
        - interval
        - amount_cents
        - amount_currency
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the plan created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        name:
          type: string
          description: The name of the plan.
          example: Startup
        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 plan will be used as the default display name.
          example: Startup plan
        created_at:
          type: string
          format: date-time
          description: The date and time when the plan was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the plan was initially created.
          example: '2023-06-27T19:43:42Z'
        code:
          type: string
          description: The code of the plan. It serves as a unique identifier associated with a particular plan. The code is typically used for internal or system-level identification purposes, like assigning a subscription, for instance.
          example: startup
        interval:
          type: string
          description: 'The interval used for recurring billing. It represents the frequency at which subscription billing occurs. The interval can be one of the following values: `yearly`, `semiannual`, `quarterly`, `monthly` or `weekly`.'
          enum:
            - weekly
            - monthly
            - quarterly
            - semiannual
            - yearly
          example: monthly
        description:
          type: string
          description: The description on the plan.
          example: ''
        amount_cents:
          type: integer
          description: The base cost of the plan, excluding any applicable taxes, that is billed on a recurring basis. This value is defined at 0 if your plan is a pay-as-you-go plan.
          example: 10000
        amount_currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of the plan. It indicates the monetary unit in which the plan's cost, including taxes and usage-based charges, is expressed.
          example: USD
        trial_period:
          type: number
          description: The duration in days during which the base cost of the plan is offered for free.
          example: 5
        pay_in_advance:
          type: boolean
          description: This field determines the billing timing for the plan. When set to `true`, the base cost of the plan is due at the beginning of each billing period. Conversely, when set to `false`, the base cost of the plan is due at the end of each billing period.
          example: true
        bill_charges_monthly:
          type:
            - boolean
            - 'null'
          description: This field, when set to `true`, enables to invoice usage-based charges on monthly basis, even if the cadence of the plan is yearly or semiannual. This allows customers to pay charges overage on a monthly basis. This can be set to true only if the plan's interval is `yearly` or `semiannual`.
          example: null
        bill_fixed_charges_monthly:
          type:
            - boolean
            - 'null'
          description: This field, when set to `true`, enables to invoice fixed charges on monthly basis, even if the cadence of the plan is yearly or semiannual. This allows customers to pay fixed charges on a monthly basis. This can be set to true only if the plan's interval is `yearly` or `semiannual`.
          example: null
        minimum_commitment:
          $ref: '#/components/schemas/MinimumCommitmentObject'
        charges:
          type: array
          items:
            $ref: '#/components/schemas/ChargeObject'
          description: Additional usage-based charges for this plan.
          example:
            - lago_id: 1a901a90-1a90-1a90-1a90-1a901a901a91
              lago_billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a91
              billable_metric_code: requests
              created_at: '2023-06-27T19:43:42Z'
              charge_model: package
              invoiceable: true
              invoice_display_name: Setup
              pay_in_advance: false
              regroup_paid_fees: null
              prorated: false
              min_amount_cents: 3000
              properties:
                amount: '30'
                free_units: 100
                package_size: 1000
              filters: []
            - lago_id: 1a901a90-1a90-1a90-1a90-1a901a901a92
              lago_billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a92
              billable_metric_code: cpu
              created_at: '2023-06-27T19:43:42Z'
              charge_model: graduated
              invoiceable: true
              invoice_display_name: Setup
              pay_in_advance: false
              regroup_paid_fees: null
              prorated: false
              min_amount_cents: 0
              properties:
                graduated_ranges:
                  - from_value: 0
                    to_value: 10
                    flat_amount: '10'
                    per_unit_amount: '0.5'
                  - from_value: 11
                    to_value: null
                    flat_amount: '0'
                    per_unit_amount: '0.4'
              filters: []
            - lago_id: 1a901a90-1a90-1a90-1a90-1a901a901a93
              lago_billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a93
              billable_metric_code: seats
              created_at: '2023-06-27T19:43:42Z'
              charge_model: standard
              invoiceable: true
              invoice_display_name: Setup
              pay_in_advance: true
              regroup_paid_fees: null
              prorated: false
              min_amount_cents: 0
              properties: {}
              filters:
                - invoice_display_name: Europe
                  properties:
                    amount: '10'
                  values:
                    region:
                      - Europe
                - invoice_display_name: USA
                  properties:
                    amount: '5'
                  values:
                    region:
                      - USA
                - invoice_display_name: Africa
                  properties:
                    amount: '8'
                  values:
                    region:
                      - Africa
            - lago_id: 1a901a90-1a90-1a90-1a90-1a901a901a94
              lago_billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a94
              billable_metric_code: storage
              created_at: '2023-06-27T19:43:42Z'
              charge_model: volume
              invoiceable: true
              invoice_display_name: Setup
              pay_in_advance: false
              regroup_paid_fees: null
              prorated: false
              min_amount_cents: 0
              properties:
                volume_ranges:
                  - from_value: 0
                    to_value: 100
                    flat_amount: '0'
                    per_unit_amount: '0'
                  - from_value: 101
                    to_value: null
                    flat_amount: '0'
                    per_unit_amount: '0.5'
              filters: []
            - lago_id: 1a901a90-1a90-1a90-1a90-1a901a901a95
              lago_billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a95
              billable_metric_code: payments
              created_at: '2023-06-27T19:43:42Z'
              charge_model: percentage
              invoiceable: false
              invoice_display_name: Setup
              pay_in_advance: true
              regroup_paid_fees: invoice
              prorated: false
              min_amount_cents: 0
              properties:
                rate: '1'
                fixed_amount: '0.5'
                free_units_per_events: 5
                free_units_per_total_aggregation: '500'
              filters: []
        fixed_charges:
          type: array
          description: List of fixed charges for this plan.
          items:
            $ref: '#/components/schemas/FixedChargeObject'
          example:
            - lago_id: 1a901a90-1a90-1a90-1a90-1a901a901a90
              lago_add_on_id: 2b802b80-2b80-2b80-2b80-2b802b802b80
              code: setup_fee
              invoice_display_name: Setup Fee
              add_on_code: setup
              created_at: '2026-01-15T10:30:00Z'
              charge_model: standard
              pay_in_advance: true
              prorated: false
              properties:
                amount: '500'
              units: 1
              lago_parent_id: null
              taxes:
                - lago_id: 3c703c70-3c70-3c70-3c70-3c703c703c70
                  name: VAT
                  code: vat_20
                  rate: 20
                  description: Standard VAT rate
                  applied_to_organization: true
                  created_at: '2026-01-01T00:00:00Z'
            - lago_id: 4d604d60-4d60-4d60-4d60-4d604d604d60
              lago_add_on_id: 5e505e50-5e50-5e50-5e50-5e505e505e50
              code: support_tier
              invoice_display_name: Support Tier
              add_on_code: premium_support
              created_at: '2026-01-15T10:30:00Z'
              charge_model: graduated
              pay_in_advance: false
              prorated: true
              properties:
                graduated_ranges:
                  - from_value: 0
                    to_value: 10
                    per_unit_amount: '5'
                    flat_amount: '200'
                  - from_value: 11
                    to_value: null
                    per_unit_amount: '1'
                    flat_amount: '300'
              units: 1
              lago_parent_id: null
              taxes: []
            - lago_id: 6f406f40-6f40-6f40-6f40-6f406f406f40
              lago_add_on_id: 7a307a30-7a30-7a30-7a30-7a307a307a30
              code: storage
              invoice_display_name: Storage Allocation
              add_on_code: cloud_storage
              created_at: '2026-01-15T10:30:00Z'
              charge_model: volume
              pay_in_advance: false
              prorated: false
              properties:
                volume_ranges:
                  - from_value: 0
                    to_value: 100
                    per_unit_amount: '2'
                    flat_amount: '1'
                  - from_value: 101
                    to_value: null
                    per_unit_amount: '1'
                    flat_amount: '0'
              units: 50
              lago_parent_id: null
              taxes: []
        taxes:
          type: array
          description: All taxes applied to the plan.
          items:
            $ref: '#/components/schemas/TaxObject'
        usage_thresholds:
          type: array
          description: List of usage thresholds applied to the plan.
          items:
            $ref: '#/components/schemas/UsageThresholdObject'
        entitlements:
          type: array
          description: List of all feature entitlements and their privileges available for this plan.
          items:
            $ref: '#/components/schemas/PlanEntitlement'
        metadata:
          $ref: '#/components/schemas/MetadataObject'
    PlansPaginated:
      type: object
      required:
        - plans
        - meta
      properties:
        plans:
          type: array
          items:
            $ref: '#/components/schemas/PlanObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    MinimumCommitmentInput:
      type:
        - object
        - 'null'
      description: Minimum commitment for this plan.
      required:
        - amount_cents
      properties:
        amount_cents:
          type: integer
          description: The amount of the minimum commitment in cents.
          example: 100000
        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 default name will be used as the display name.
          example: Minimum Commitment (C1)
        tax_codes:
          $ref: '#/components/schemas/TaxCodes'
    ChargeFilterInput:
      type: object
      description: Values used to apply differentiated pricing based on additional event properties.
      required:
        - properties
        - values
      properties:
        invoice_display_name:
          type:
            - string
            - 'null'
          description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the values of the filter will be used as the default display name.
          example: AWS
        properties:
          $ref: '#/components/schemas/ChargeProperties'
          description: List of all thresholds utilized for calculating the charge.
        values:
          type: object
          description: List of possible filter values. The key and values must match one of the billable metric filters.
          additionalProperties:
            type: array
            items:
              type: string
          example:
            region:
              - us-east-1
    UsageThresholdInput:
      type: object
      required:
        - amount_cents
      properties:
        threshold_display_name:
          type:
            - string
            - 'null'
          description: The display name of the usage threshold.
          example: Threshold 1
        amount_cents:
          type: integer
          description: The amount to reach to trigger a `progressive_billing` invoice.
          example: 10000
        recurring:
          type: boolean
          description: This field when set to `true` indicates that a `progressive_billing` invoice will be created every time the lifetime usage increases by the specified amount.
          example: true
          default: false
    PlanCreateInput:
      type: object
      required:
        - plan
      properties:
        plan:
          type: object
          required:
            - name
            - code
            - interval
            - amount_cents
            - amount_currency
            - pay_in_advance
          properties:
            name:
              type: string
              example: Startup
              description: The name of the plan.
            invoice_display_name:
              type:
                - string
                - 'null'
              example: Startup plan
              description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the plan will be used as the default display name.
            code:
              type: string
              example: startup
              description: The code of the plan. It serves as a unique identifier associated with a particular plan. The code is typically used for internal or system-level identification purposes, like assigning a subscription, for instance.
            interval:
              type: string
              description: 'The interval used for recurring billing. It represents the frequency at which subscription billing occurs. The interval can be one of the following values: `yearly`, `semiannual`, `quarterly`, `monthly`, or `weekly`.'
              example: monthly
              enum:
                - weekly
                - monthly
                - quarterly
                - semiannual
                - yearly
            description:
              type:
                - string
                - 'null'
              description: The description on the plan.
              example: Plan for early stage startups.
            amount_cents:
              type: integer
              description: The base cost of the plan, excluding any applicable taxes, that is billed on a recurring basis. This value is defined at 0 if your plan is a pay-as-you-go plan.
              example: 10000
            amount_currency:
              $ref: '#/components/schemas/Currency'
              description: The currency of the plan. It indicates the monetary unit in which the plan's cost, including taxes and usage-based charges, is expressed.
              example: USD
            trial_period:
              type:
                - number
                - 'null'
              description: The duration in days during which the base cost of the plan is offered for free.
              example: 5
            pay_in_advance:
              type: boolean
              description: This field determines the billing timing for the plan. When set to `true`, the base cost of the plan is due at the beginning of each billing period. Conversely, when set to `false`, the base cost of the plan is due at the end of each billing period.
              example: true
            bill_charges_monthly:
              type:
                - boolean
                - 'null'
              description: This field, when set to `true`, enables to invoice usage-based charges on monthly basis, even if the cadence of the plan is `yearly` or `semiannual`. This allows customers to pay charges overage on a monthly basis. This can be set to true only if the plan's interval is `yearly` or `semiannual`.
              example: null
            bill_fixed_charges_monthly:
              type:
                - boolean
                - 'null'
              description: This field, when set to `true`, enables to invoice fixed charges on monthly basis, even if the cadence of the plan is `yearly` or `semiannual`. This allows customers to pay fixed charges on a monthly basis. This can be set to true only if the plan's interval is `yearly` or `semiannual`.
              example: null
            tax_codes:
              $ref: '#/components/schemas/TaxCodes'
            minimum_commitment:
              $ref: '#/components/schemas/MinimumCommitmentInput'
            charges:
              type: array
              description: Additional usage-based charges for this plan.
              items:
                type: object
                required:
                  - billable_metric_id
                  - charge_model
                properties:
                  billable_metric_id:
                    type: string
                    format: uuid
                    description: Unique identifier of the billable metric created by Lago.
                    example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                  code:
                    type: string
                    description: Unique code identifying the charge within the plan.
                    example: api_requests_charge
                  charge_model:
                    $ref: '#/components/schemas/ChargeModelEnum'
                  pay_in_advance:
                    type: boolean
                    example: false
                    description: This field determines the billing timing for this specific usage-based charge. When set to `true`, the charge is due and invoiced immediately. Conversely, when set to false, the charge is due and invoiced at the end of each billing period.
                  invoiceable:
                    type: boolean
                    description: This field specifies whether the charge should be included in a proper invoice. If set to false, no invoice will be issued for this charge. You can only set it to `false` when `pay_in_advance` is `true`.
                    example: true
                  regroup_paid_fees:
                    type:
                      - string
                      - 'null'
                    enum:
                      - null
                      - invoice
                    description: |-
                      This setting can only be configured if `pay_in_advance` is `true` and `invoiceable` is `false`.
                      This field determines whether and when the charge fee should be included in
                      the invoice. If `null`, no invoice will be issued for this charge fee.
                      If `invoice`, an invoice will be generated at the end of the period,
                      consolidating all charge fees with a succeeded payment status.
                    example: invoice
                  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
                  prorated:
                    type: boolean
                    example: false
                    description: |-
                      Specifies whether a charge is prorated based on the remaining number of days in the billing period or billed fully.

                      - If set to `true`, the charge is prorated based on the remaining days in the current billing period.
                      - If set to `false`, the charge is billed in full.
                      - If not defined in the request, default value is `false`.
                  min_amount_cents:
                    type: integer
                    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/ChargeObjectProperties'
                    description: List of all thresholds utilized for calculating the charge.
                  filters:
                    type: array
                    description: List of filters used to apply differentiated pricing based on additional event properties.
                    items:
                      $ref: '#/components/schemas/ChargeFilterInput'
                  tax_codes:
                    $ref: '#/components/schemas/TaxCodes'
                  applied_pricing_unit:
                    type: object
                    description: The pricing unit to apply to the charge.
                    properties:
                      code:
                        type: string
                        description: The code of the pricing unit.
                        example: credits
                      conversion_rate:
                        type: string
                        description: |-
                          The conversion rate from pricing units to the plan's currency.
                          This rate determines how many currency units (in the plan's base currency) equal one pricing unit.
                          For example, if the plan uses USD and the conversion rate is 0.5, then 1 pricing unit = $0.50.
                        example: '0.5'
                  accepts_target_wallet:
                    type:
                      - boolean
                      - 'null'
                    description: Specifies whether the charge accepts a target wallet for prepaid credits deduction.
                    example: false
              example:
                - billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a91
                  charge_model: package
                  invoiceable: true
                  invoice_display_name: Setup
                  pay_in_advance: false
                  regroup_paid_fees: null
                  prorated: false
                  min_amount_cents: 3000
                  properties:
                    amount: '30'
                    free_units: 100
                    package_size: 1000
                  tax_codes:
                    - french_standard_vat
                - billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a92
                  charge_model: graduated
                  invoiceable: true
                  invoice_display_name: Setup
                  pay_in_advance: false
                  prorated: false
                  min_amount_cents: 0
                  properties:
                    graduated_ranges:
                      - to_value: 10
                        from_value: 0
                        flat_amount: '10'
                        per_unit_amount: '0.5'
                      - to_value: null
                        from_value: 11
                        flat_amount: '0'
                        per_unit_amount: '0.4'
                - billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a93
                  charge_model: standard
                  invoiceable: true
                  invoice_display_name: Setup
                  pay_in_advance: true
                  prorated: false
                  min_amount_cents: 0
                  properties: {}
                - billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a94
                  charge_model: volume
                  invoiceable: true
                  invoice_display_name: Setup
                  pay_in_advance: false
                  prorated: false
                  min_amount_cents: 0
                  properties:
                    volume_ranges:
                      - from_value: 0
                        to_value: 100
                        flat_amount: '0'
                        per_unit_amount: '0'
                      - from_value: 101
                        to_value: null
                        flat_amount: '0'
                        per_unit_amount: '0.5'
                - billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a95
                  charge_model: percentage
                  invoiceable: false
                  invoice_display_name: Setup
                  pay_in_advance: true
                  regroup_paid_fees: invoice
                  prorated: false
                  min_amount_cents: 0
                  properties:
                    rate: '1'
                    fixed_amount: '0.5'
                    free_units_per_events: 5
                    free_units_per_total_aggregation: '500'
            fixed_charges:
              type: array
              description: Additional fixed charges for this plan.
              items:
                type: object
                required:
                  - add_on_id
                  - charge_model
                properties:
                  add_on_id:
                    type: string
                    format: uuid
                    description: Unique identifier of the add-on associated with this fixed charge.
                    example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                  code:
                    type: string
                    description: Unique code for the fixed charge. If not provided, it will be automatically generated based on the add-on code.
                    example: setup_fee
                  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 fee
                  units:
                    type: number
                    description: The number of units for the fixed charge. Defaults to 0 if not provided.
                    example: 1
                    default: 0
                  charge_model:
                    type: string
                    enum:
                      - standard
                      - graduated
                      - volume
                    description: The charge model for the fixed charge. Only `standard`, `graduated`, and `volume` models are supported for fixed charges.
                    example: standard
                  pay_in_advance:
                    type: boolean
                    description: This field determines the billing timing for this specific fixed charge. When set to `true`, the charge is due and invoiced immediately. Conversely, when set to false, the charge is due and invoiced at the end of each billing period. Defaults to `false` if not provided.
                    example: false
                    default: false
                  prorated:
                    type: boolean
                    description: |
                      Specifies whether a fixed charge is prorated based on the remaining number of days in the billing period or billed fully.

                      - If set to `true`, the charge is prorated based on the remaining days in the current billing period.
                      - If set to `false`, the charge is billed in full.
                      - Defaults to `false` if not provided.

                      Note: Prorated fixed charges with `graduated` model and `pay_in_advance` are not allowed.
                    example: false
                    default: false
                  properties:
                    $ref: '#/components/schemas/FixedChargeProperties'
                    description: List of all thresholds utilized for calculating the fixed charge.
                  tax_codes:
                    $ref: '#/components/schemas/TaxCodes'
                    description: List of taxes applied to the fixed charge.
              example:
                - add_on_id: 1a901a90-1a90-1a90-1a90-1a901a901a90
                  code: setup_fee
                  invoice_display_name: Setup Fee
                  charge_model: standard
                  pay_in_advance: true
                  prorated: false
                  properties:
                    amount: '500'
                  units: 1
                  tax_codes:
                    - french_standard_vat
                - add_on_id: 4d604d60-4d60-4d60-4d60-4d604d604d60
                  invoice_display_name: Support Tier
                  charge_model: graduated
                  pay_in_advance: false
                  prorated: true
                  properties:
                    graduated_ranges:
                      - from_value: 0
                        to_value: 10
                        per_unit_amount: '5'
                        flat_amount: '200'
                      - from_value: 11
                        to_value: null
                        per_unit_amount: '1'
                        flat_amount: '300'
                  units: 2
                - add_on_id: 6f406f40-6f40-6f40-6f40-6f406f406f40
                  charge_model: volume
                  properties:
                    volume_ranges:
                      - from_value: 0
                        to_value: 100
                        per_unit_amount: '2'
                        flat_amount: '1'
                      - from_value: 101
                        to_value: null
                        per_unit_amount: '1'
                        flat_amount: '0'
                  units: 50
            usage_thresholds:
              type: array
              description: List of usage thresholds to apply to the plan.
              items:
                $ref: '#/components/schemas/UsageThresholdInput'
            metadata:
              $ref: '#/components/schemas/MetadataInput'
    Plan:
      type: object
      required:
        - plan
      properties:
        plan:
          $ref: '#/components/schemas/PlanObject'
    PlanUpdateInput:
      type: object
      required:
        - plan
      properties:
        plan:
          type: object
          properties:
            name:
              type: string
              example: Startup
              description: The name of the plan.
            invoice_display_name:
              type:
                - string
                - 'null'
              example: Startup plan
              description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the plan will be used as the default display name.
            code:
              type: string
              example: startup
              description: The code of the plan. It serves as a unique identifier associated with a particular plan. The code is typically used for internal or system-level identification purposes, like assigning a subscription, for instance.
            interval:
              type: string
              description: 'The interval used for recurring billing. It represents the frequency at which subscription billing occurs. The interval can be one of the following values: `yearly`, `semiannual`, `quarterly`, `monthly`, or `weekly`.'
              example: monthly
              enum:
                - weekly
                - monthly
                - quarterly
                - semiannual
                - yearly
            description:
              type:
                - string
                - 'null'
              description: The description on the plan.
              example: Plan for early stage startups.
            amount_cents:
              type: integer
              description: The base cost of the plan, excluding any applicable taxes, that is billed on a recurring basis. This value is defined at 0 if your plan is a pay-as-you-go plan.
              example: 10000
            amount_currency:
              $ref: '#/components/schemas/Currency'
              description: The currency of the plan. It indicates the monetary unit in which the plan's cost, including taxes and usage-based charges, is expressed.
              example: USD
            trial_period:
              type:
                - number
                - 'null'
              description: The duration in days during which the base cost of the plan is offered for free.
              example: 5
            pay_in_advance:
              type: boolean
              description: This field determines the billing timing for the plan. When set to `true`, the base cost of the plan is due at the beginning of each billing period. Conversely, when set to `false`, the base cost of the plan is due at the end of each billing period.
              example: true
            bill_charges_monthly:
              type:
                - boolean
                - 'null'
              description: This field, when set to `true`, enables to invoice usage-based charges on monthly basis, even if the cadence of the plan is yearly or semiannual. This allows customers to pay charges overage on a monthly basis. This can be set to true only if the plan's interval is `yearly` or `semiannual`.
              example: null
            bill_fixed_charges_monthly:
              type:
                - boolean
                - 'null'
              description: This field, when set to `true`, enables to invoice fixed charges on monthly basis, even if the cadence of the plan is `yearly` or `semiannual`. This allows customers to pay fixed charges on a monthly basis. This can be set to true only if the plan's interval is `yearly` or `semiannual`.
              example: null
            tax_codes:
              $ref: '#/components/schemas/TaxCodes'
            minimum_commitment:
              $ref: '#/components/schemas/MinimumCommitmentInput'
            charges:
              type: array
              description: Additional usage-based charges for this plan.
              items:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Unique identifier of the charge created by Lago.
                    example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                  billable_metric_id:
                    type: string
                    format: uuid
                    description: Unique identifier of the billable metric created by Lago.
                    example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                  code:
                    type: string
                    description: Unique code identifying the charge within the plan.
                    example: api_requests_charge
                  charge_model:
                    $ref: '#/components/schemas/ChargeModelEnum'
                  pay_in_advance:
                    type: boolean
                    example: false
                    description: This field determines the billing timing for this specific usage-based charge. When set to `true`, the charge is due and invoiced immediately. Conversely, when set to false, the charge is due and invoiced at the end of each billing period.
                  invoiceable:
                    type: boolean
                    description: This field specifies whether the charge should be included in a proper invoice. If set to false, no invoice will be issued for this charge. You can only set it to `false` when `pay_in_advance` is `true`.
                    example: true
                  regroup_paid_fees:
                    type:
                      - string
                      - 'null'
                    enum:
                      - null
                      - invoice
                    description: |-
                      This setting can only be configured if `pay_in_advance` is `true` and `invoiceable` is `false`.
                      This field determines whether and when the charge fee should be included in
                      the invoice. If `null`, no invoice will be issued for this charge fee.
                      If `invoice`, an invoice will be generated at the end of the period,
                      consolidating all charge fees with a succeeded payment status.
                    example: invoice
                  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
                  prorated:
                    type: boolean
                    example: false
                    description: |-
                      Specifies whether a charge is prorated based on the remaining number of days in the billing period or billed fully.

                      - If set to `true`, the charge is prorated based on the remaining days in the current billing period.
                      - If set to `false`, the charge is billed in full.
                      - If not defined in the request, default value is `false`.
                  min_amount_cents:
                    type: integer
                    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/ChargeObjectProperties'
                    description: List of all thresholds utilized for calculating the charge.
                  filters:
                    type: array
                    description: List of filters used to apply differentiated pricing based on additional event properties.
                    items:
                      $ref: '#/components/schemas/ChargeFilterInput'
                  tax_codes:
                    $ref: '#/components/schemas/TaxCodes'
                  applied_pricing_unit:
                    type: object
                    description: Updates the pricing unit conversion rate for this charge. Only applies if the charge has applied pricing unit.
                    properties:
                      conversion_rate:
                        type: string
                        description: |-
                          The conversion rate from pricing units to the plan's currency.
                          This rate determines how many currency units (in the plan's base currency) equal one pricing unit.
                          For example, if the plan uses USD and the conversion rate is 0.5, then 1 pricing unit = $0.50 USD.
                        example: '0.5'
                  accepts_target_wallet:
                    type:
                      - boolean
                      - 'null'
                    description: Specifies whether the charge accepts a target wallet for prepaid credits deduction.
                    example: false
              example:
                - billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a91
                  charge_model: package
                  invoiceable: true
                  invoice_display_name: Setup
                  pay_in_advance: false
                  prorated: false
                  min_amount_cents: 3000
                  properties:
                    amount: '30'
                    free_units: 100
                    package_size: 1000
                  tax_codes:
                    - french_standard_vat
                - billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a92
                  charge_model: graduated
                  invoiceable: true
                  invoice_display_name: Setup
                  pay_in_advance: false
                  prorated: false
                  min_amount_cents: 0
                  properties:
                    graduated_ranges:
                      - to_value: 10
                        from_value: 0
                        flat_amount: '10'
                        per_unit_amount: '0.5'
                      - to_value: null
                        from_value: 11
                        flat_amount: '0'
                        per_unit_amount: '0.4'
                - billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a93
                  charge_model: standard
                  invoiceable: true
                  invoice_display_name: Setup
                  pay_in_advance: true
                  regroup_paid_fees: null
                  prorated: false
                  min_amount_cents: 0
                  properties: {}
                - billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a94
                  charge_model: volume
                  invoiceable: true
                  invoice_display_name: Setup
                  pay_in_advance: false
                  prorated: false
                  min_amount_cents: 0
                  properties:
                    volume_ranges:
                      - from_value: 0
                        to_value: 100
                        flat_amount: '0'
                        per_unit_amount: '0'
                      - from_value: 101
                        to_value: null
                        flat_amount: '0'
                        per_unit_amount: '0.5'
                - billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a95
                  charge_model: percentage
                  invoiceable: false
                  invoice_display_name: Setup
                  pay_in_advance: true
                  regroup_paid_fees: invoice
                  prorated: false
                  min_amount_cents: 0
                  properties:
                    rate: '1'
                    fixed_amount: '0.5'
                    free_units_per_events: 5
                    free_units_per_total_aggregation: '500'
            fixed_charges:
              type: array
              description: Additional fixed charges for this plan.
              items:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Unique identifier of the fixed charge created by Lago (required for updates).
                    example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                  add_on_id:
                    type: string
                    format: uuid
                    description: Unique identifier of the add-on associated with this fixed charge.
                    example: 1a901a90-1a90-1a90-1a90-1a901a901a90
                  code:
                    type: string
                    description: Unique code for the fixed charge. If not provided, it will be automatically generated based on the add-on code.
                    example: setup_fee
                  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 fee
                  units:
                    type: number
                    description: The number of units for the fixed charge. Defaults to 0 if not provided.
                    example: 1
                    default: 0
                  charge_model:
                    type: string
                    enum:
                      - standard
                      - graduated
                      - volume
                    description: The charge model for the fixed charge. Only `standard`, `graduated`, and `volume` models are supported for fixed charges.
                    example: standard
                  pay_in_advance:
                    type: boolean
                    description: This field determines the billing timing for this specific fixed charge. When set to `true`, the charge is due and invoiced immediately. Conversely, when set to false, the charge is due and invoiced at the end of each billing period. Defaults to `false` if not provided.
                    example: false
                    default: false
                  prorated:
                    type: boolean
                    description: |
                      Specifies whether a fixed charge is prorated based on the remaining number of days in the billing period or billed fully.

                      - If set to `true`, the charge is prorated based on the remaining days in the current billing period.
                      - If set to `false`, the charge is billed in full.
                      - Defaults to `false` if not provided.

                      Note: Prorated fixed charges with `graduated` model and `pay_in_advance` are not allowed.
                    example: false
                    default: false
                  properties:
                    $ref: '#/components/schemas/FixedChargeProperties'
                    description: List of all thresholds utilized for calculating the fixed charge.
                  tax_codes:
                    $ref: '#/components/schemas/TaxCodes'
                    description: List of taxes applied to the fixed charge.
                  apply_units_immediately:
                    type: boolean
                    description: Determines if the units should be applied immediately upon assignment or deferred to the next billing cycle.
                    example: true
              example:
                - id: 1a901a90-1a90-1a90-1a90-1a901a901a90
                  invoice_display_name: New Setup Fee
                  charge_model: standard
                  apply_units_immediately: true
                  units: 5
                - add_on_id: 1a901a90-1a90-1a90-1a90-1a901a901a90
                  code: setup_fee
                  invoice_display_name: Setup Fee
                  charge_model: standard
                  pay_in_advance: true
                  prorated: false
                  properties:
                    amount: '500'
                  units: 1
                  apply_units_immediately: false
                  tax_codes:
                    - french_standard_vat
                - add_on_id: 4d604d60-4d60-4d60-4d60-4d604d604d60
                  invoice_display_name: Support Tier
                  charge_model: graduated
                  pay_in_advance: false
                  prorated: true
                  properties:
                    graduated_ranges:
                      - from_value: 0
                        to_value: 10
                        per_unit_amount: '5'
                        flat_amount: '200'
                      - from_value: 11
                        to_value: null
                        per_unit_amount: '1'
                        flat_amount: '300'
                  units: 2
                - add_on_id: 6f406f40-6f40-6f40-6f40-6f406f406f40
                  charge_model: volume
                  properties:
                    volume_ranges:
                      - from_value: 0
                        to_value: 100
                        per_unit_amount: '2'
                        flat_amount: '1'
                      - from_value: 101
                        to_value: null
                        per_unit_amount: '1'
                        flat_amount: '0'
                  units: 50
            usage_thresholds:
              type: array
              description: List of usage thresholds to apply to the plan.
              items:
                $ref: '#/components/schemas/UsageThresholdInput'
            cascade_updates:
              type: boolean
              description: This field determines whether the changes made to the plan should be cascaded to the children plans. When set to `true`, the changes will be cascaded into children. Conversely, when set to `false`, the changes will only be applied to the plan itself. If not defined in the request, default value is `false`.
              example: true
            metadata:
              $ref: '#/components/schemas/MetadataInput'
    PlanEntitlements:
      type: object
      required:
        - entitlements
      properties:
        entitlements:
          type: array
          items:
            $ref: '#/components/schemas/PlanEntitlementObject'
    EntitlementUpdateInput:
      type: object
      required:
        - entitlements
      properties:
        entitlements:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              oneOf:
                - type: integer
                - type: boolean
                - type: string
            description: Privilege values for this feature. All privileges must exist on the feature.
          example:
            seats:
              max: 20
              max_admins: 10
              root: false
            sso:
              provider: okta
          description: Feature entitlements with their privilege values. Each key is a feature code, and the value is an object containing privilege codes with their associated values.
    PlanMetadataResponse:
      type: object
      required:
        - metadata
      properties:
        metadata:
          $ref: '#/components/schemas/MetadataObject'
    ChargesPaginated:
      type: object
      required:
        - charges
        - meta
      properties:
        charges:
          type: array
          items:
            $ref: '#/components/schemas/ChargeObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    ChargeOverridableInput:
      type: object
      description: Properties of a charge that can be overridden at the subscription level.
      properties:
        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
        min_amount_cents:
          type: integer
          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/ChargeObjectProperties'
          description: List of all thresholds utilized for calculating the charge.
        filters:
          type: array
          description: List of filters used to apply differentiated pricing based on additional event properties.
          items:
            $ref: '#/components/schemas/ChargeFilterInput'
        tax_codes:
          $ref: '#/components/schemas/TaxCodes'
        applied_pricing_unit:
          type: object
          description: The pricing unit to apply to the charge.
          properties:
            code:
              type: string
              description: The code of the pricing unit.
              example: credits
            conversion_rate:
              type: string
              description: |-
                The conversion rate from pricing units to the plan's currency.
                This rate determines how many currency units (in the plan's base currency) equal one pricing unit.
                For example, if the plan uses USD and the conversion rate is 0.5, then 1 pricing unit = $0.50.
              example: '0.5'
    ChargeInput:
      allOf:
        - $ref: '#/components/schemas/ChargeOverridableInput'
        - type: object
          properties:
            billable_metric_id:
              type: string
              format: uuid
              description: Unique identifier of the billable metric created by Lago.
              example: 1a901a90-1a90-1a90-1a90-1a901a901a90
            code:
              type: string
              description: Unique code identifying the charge within the plan.
              example: api_requests_charge
            charge_model:
              $ref: '#/components/schemas/ChargeModelEnum'
            pay_in_advance:
              type: boolean
              example: false
              description: This field determines the billing timing for this specific usage-based charge. When set to `true`, the charge is due and invoiced immediately. Conversely, when set to false, the charge is due and invoiced at the end of each billing period.
            invoiceable:
              type: boolean
              description: This field specifies whether the charge should be included in a proper invoice. If set to false, no invoice will be issued for this charge. You can only set it to `false` when `pay_in_advance` is `true`.
              example: true
            regroup_paid_fees:
              type:
                - string
                - 'null'
              enum:
                - null
                - invoice
              description: |-
                This setting can only be configured if `pay_in_advance` is `true` and `invoiceable` is `false`.
                This field determines whether and when the charge fee should be included in
                the invoice. If `null`, no invoice will be issued for this charge fee.
                If `invoice`, an invoice will be generated at the end of the period,
                consolidating all charge fees with a succeeded payment status.
              example: null
            prorated:
              type: boolean
              example: false
              description: |-
                Specifies whether a charge is prorated based on the remaining number of days in the billing period or billed fully.

                - If set to `true`, the charge is prorated based on the remaining days in the current billing period.
                - If set to `false`, the charge is billed in full.
                - If not defined in the request, default value is `false`.
    ChargeCreateInput:
      type: object
      required:
        - charge
      properties:
        charge:
          allOf:
            - $ref: '#/components/schemas/ChargeInput'
            - required:
                - billable_metric_id
                - charge_model
            - properties:
                cascade_updates:
                  type: boolean
                  description: This field determines whether the creation of the charge should be cascaded to the children plans. When set to `true`, the charge will be created in children plans. Conversely, when set to `false`, the charge will only be created in the plan itself. If not defined in the request, default value is `false`.
                  example: true
    Charge:
      type: object
      required:
        - charge
      properties:
        charge:
          $ref: '#/components/schemas/ChargeObject'
    ChargeUpdateInput:
      type: object
      required:
        - charge
      properties:
        charge:
          allOf:
            - $ref: '#/components/schemas/ChargeInput'
            - properties:
                cascade_updates:
                  type: boolean
                  description: This field determines whether the changes made to the charge should be cascaded to the children plans. When set to `true`, the changes will be cascaded into children. Conversely, when set to `false`, the changes will only be applied to the plan itself. If not defined in the request, default value is `false`.
                  example: true
    ChargeDeleteInput:
      type: object
      properties:
        charge:
          type: object
          properties:
            cascade_updates:
              type: boolean
              description: When set to `true`, the deletion will be cascaded to the children plans.
              example: true
    ChargeFilterFullObject:
      type: object
      description: Charge filter values used to apply differentiated pricing based on additional event properties.
      required:
        - lago_id
        - charge_code
        - invoice_display_name
        - properties
        - values
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the charge filter, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        charge_code:
          type: string
          description: Unique code identifying the charge this filter belongs to.
          example: api_requests_charge
        invoice_display_name:
          type:
            - string
            - 'null'
          description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the values of the filter will be used as the default display name.
          example: AWS
        properties:
          $ref: '#/components/schemas/ChargeProperties'
          description: List of all thresholds utilized for calculating the charge.
        values:
          type: object
          description: List of possible filter values. The key and values must match one of the billable metric filters.
          additionalProperties:
            type: array
            items:
              type: string
          example:
            region:
              - us-east-1
    ChargeFiltersPaginated:
      type: object
      required:
        - filters
        - meta
      properties:
        filters:
          type: array
          items:
            $ref: '#/components/schemas/ChargeFilterFullObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    ChargeFilterCreateInput:
      type: object
      required:
        - filter
      properties:
        filter:
          type: object
          required:
            - properties
            - values
          properties:
            cascade_updates:
              type: boolean
              description: This field determines whether the creation of the filter should be cascaded to the children plans. When set to `true`, the changes will be cascaded into children. Conversely, when set to `false`, the changes will only be applied to the plan itself. If not defined in the request, default value is `false`.
              example: true
            invoice_display_name:
              type:
                - string
                - 'null'
              description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the values of the filter will be used as the default display name.
              example: AWS
            properties:
              $ref: '#/components/schemas/ChargeProperties'
              description: List of all thresholds utilized for calculating the charge.
            values:
              type: object
              description: List of possible filter values. The key and values must match one of the billable metric filters.
              additionalProperties:
                type: array
                items:
                  type: string
              example:
                region:
                  - us-east-1
    ChargeFilterResponse:
      type: object
      required:
        - filter
      properties:
        filter:
          $ref: '#/components/schemas/ChargeFilterFullObject'
    ChargeFilterUpdateInput:
      type: object
      required:
        - filter
      properties:
        filter:
          type: object
          properties:
            cascade_updates:
              type: boolean
              description: This field determines whether the changes made to the filter should be cascaded to the children plans. When set to `true`, the changes will be cascaded into children. Conversely, when set to `false`, the changes will only be applied to the plan itself. If not defined in the request, default value is `false`.
              example: true
            invoice_display_name:
              type:
                - string
                - 'null'
              description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the values of the filter will be used as the default display name.
              example: AWS
            properties:
              $ref: '#/components/schemas/ChargeProperties'
              description: List of all thresholds utilized for calculating the charge.
            values:
              type: object
              description: List of possible filter values. The key and values must match one of the billable metric filters.
              additionalProperties:
                type: array
                items:
                  type: string
              example:
                region:
                  - us-east-1
    ChargeFilterDeleteInput:
      type: object
      properties:
        filter:
          type: object
          properties:
            cascade_updates:
              type: boolean
              description: When set to `true`, the deletion will be cascaded to the children plans.
              example: true
    FixedChargesPaginated:
      type: object
      required:
        - fixed_charges
        - meta
      properties:
        fixed_charges:
          type: array
          items:
            $ref: '#/components/schemas/FixedChargeObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    FixedChargeOverridableInput:
      type: object
      description: Properties of a fixed charge that can be overridden at the subscription level.
      properties:
        invoice_display_name:
          type:
            - string
            - 'null'
          description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the add-on will be used as the default display name.
          example: Setup Fee
        units:
          type: string
          description: The quantity of units for the fixed charge.
          example: '1.0'
        apply_units_immediately:
          type: boolean
          description: When set to `true`, the fixed charge units are applied immediately for active subscriptions. When set to `false`, the units are applied at the next billing period.
          example: false
        properties:
          $ref: '#/components/schemas/ChargeProperties'
          description: List of all thresholds utilized for calculating the fixed charge.
        tax_codes:
          $ref: '#/components/schemas/TaxCodes'
    FixedChargeModelEnum:
      type: string
      description: |
        Specifies the pricing model used for the calculation of the fixed charge fee. It can be any of the following values:
          - `standard`
          - `graduated`
          - `volume`
      enum:
        - standard
        - graduated
        - volume
    FixedChargeInput:
      allOf:
        - $ref: '#/components/schemas/FixedChargeOverridableInput'
        - type: object
          properties:
            add_on_id:
              type: string
              format: uuid
              description: Unique identifier of the add-on. Either add_on_id or add_on_code is required.
              example: 1a901a90-1a90-1a90-1a90-1a901a901a90
            add_on_code:
              type: string
              description: Unique code identifying an add-on. Either add_on_id or add_on_code is required.
              example: setup_fee
            code:
              type: string
              description: Unique code identifying the fixed charge within the plan.
              example: setup_fee_charge
            charge_model:
              $ref: '#/components/schemas/FixedChargeModelEnum'
            pay_in_advance:
              type: boolean
              description: This field determines the billing timing for this fixed charge. When set to `true`, the charge is due and invoiced immediately at the beginning of the billing period. When set to `false`, the charge is due and invoiced at the end of the billing period.
              example: true
            prorated:
              type: boolean
              example: false
              description: |-
                Specifies whether a fixed charge is prorated based on the remaining number of days in the billing period or billed fully.

                - If set to `true`, the charge is prorated based on the remaining days in the current billing period.
                - If set to `false`, the charge is billed in full.
    FixedChargeCreateInput:
      type: object
      required:
        - fixed_charge
      properties:
        fixed_charge:
          allOf:
            - $ref: '#/components/schemas/FixedChargeInput'
            - properties:
                cascade_updates:
                  type: boolean
                  description: This field determines whether the creation of the fixed charge should be cascaded to the children plans. When set to `true`, the fixed charge will be created in children plans. Conversely, when set to `false`, the fixed charge will only be created in the plan itself. If not defined in the request, default value is `false`.
                  example: true
    FixedCharge:
      type: object
      required:
        - fixed_charge
      properties:
        fixed_charge:
          $ref: '#/components/schemas/FixedChargeObject'
    FixedChargeUpdateInput:
      type: object
      required:
        - fixed_charge
      properties:
        fixed_charge:
          allOf:
            - $ref: '#/components/schemas/FixedChargeInput'
            - properties:
                cascade_updates:
                  type: boolean
                  description: This field determines whether the changes made to the fixed charge should be cascaded to the children plans. When set to `true`, the changes will be cascaded into children. Conversely, when set to `false`, the changes will only be applied to the plan itself. If not defined in the request, default value is `false`.
                  example: true
    FixedChargeDeleteInput:
      type: object
      properties:
        fixed_charge:
          type: object
          properties:
            cascade_updates:
              type: boolean
              description: When set to `true`, the deletion will be cascaded to the children plans.
              example: true
    PlanOverridesObject:
      type: object
      description: Based plan overrides.
      properties:
        amount_cents:
          type: integer
          description: The base cost of the plan, excluding any applicable taxes, that is billed on a recurring basis. This value is defined at 0 if your plan is a pay-as-you-go plan.
          example: 10000
        amount_currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of the plan. It indicates the monetary unit in which the plan's cost, including taxes and usage-based charges, is expressed.
          example: USD
        description:
          type: string
          description: The description on the plan.
          example: Plan for early stage startups.
        invoice_display_name:
          type: string
          example: Startup plan
          description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the plan will be used as the default display name.
        name:
          type: string
          example: Startup
          description: The name of the plan.
        tax_codes:
          $ref: '#/components/schemas/TaxCodes'
        trial_period:
          type: number
          description: The duration in days during which the base cost of the plan is offered for free.
          example: 5
        minimum_commitment:
          $ref: '#/components/schemas/MinimumCommitmentInput'
        charges:
          type: array
          description: Additional usage-based charges for this plan.
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                description: Unique identifier of the charge created by Lago.
                example: 1a901a90-1a90-1a90-1a90-1a901a901a90
              billable_metric_id:
                type: string
                format: uuid
                description: Unique identifier of the billable metric created by Lago.
                example: 1a901a90-1a90-1a90-1a90-1a901a901a90
              code:
                type: string
                description: Unique code identifying the charge within the plan.
                example: api_requests_charge
              charge_model:
                $ref: '#/components/schemas/ChargeModelEnum'
              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
              min_amount_cents:
                type: integer
                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/ChargeObjectProperties'
                description: List of all thresholds utilized for calculating the charge.
              filters:
                type: array
                description: List of filters used to apply differentiated pricing based on additional event properties.
                items:
                  $ref: '#/components/schemas/ChargeFilterInput'
              tax_codes:
                $ref: '#/components/schemas/TaxCodes'
              applied_pricing_unit:
                type: object
                description: Updates the pricing unit conversion rate for this charge. Only applies if the charge has applied pricing unit.
                properties:
                  conversion_rate:
                    type: string
                    description: |-
                      The conversion rate from pricing units to the plan's currency.
                      This rate determines how many currency units (in the plan's base currency) equal one pricing unit.
                      For example, if the plan uses USD and the conversion rate is 0.5, then 1 pricing unit = $0.50 USD.
                    example: '0.5'
        fixed_charges:
          type: array
          description: Fixed charge overrides for the subscription. When `plan_overrides` contains only `fixed_charges` and every entry contains only `id`, `units`, and optionally `apply_units_immediately`, the units are recorded as a per-subscription override without creating a plan override, and subscription-scoped reads return these units. If any entry carries other fields, or `plan_overrides` contains any other key, the request is applied as a full plan override for the subscription instead.
          items:
            type: object
            required:
              - id
            properties:
              id:
                type: string
                format: uuid
                description: Unique identifier of the fixed charge created by Lago.
                example: 1a901a90-1a90-1a90-1a90-1a901a901a90
              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 fee
              units:
                type: number
                description: The number of units for the fixed charge. Defaults to 0 if not provided.
                example: 1
                default: 0
              apply_units_immediately:
                type: boolean
                description: Determines if the units should be applied immediately upon assignment or deferred to the next billing cycle.
                example: true
              properties:
                $ref: '#/components/schemas/FixedChargeProperties'
                description: List of all thresholds utilized for calculating the fixed charge.
              tax_codes:
                $ref: '#/components/schemas/TaxCodes'
                description: List of taxes applied to the fixed charge.
        usage_thresholds:
          type: array
          description: List of usage thresholds applied to the subscription.
          items:
            $ref: '#/components/schemas/UsageThresholdInput'
        metadata:
          $ref: '#/components/schemas/MetadataInput'
    SubscriptionActivationRuleInput:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: The type of the activation rule. Only `payment` is currently supported. A `payment` rule gates the subscription activation on a successful payment of the first invoice.
          example: payment
          enum:
            - payment
        timeout_hours:
          type: integer
          description: The number of hours the subscription stays in the `incomplete` state waiting for the payment to succeed before it is automatically canceled. Must be a positive integer or zero.
          example: 48
    SubscriptionCreateInput:
      type: object
      required:
        - subscription
      properties:
        authorization:
          type: object
          description: |
            Optionally, you can create a pre-authorization on the customer's card before creating a subscription. This process places a temporary hold (capture) for a specified amount on the customer's account, but does not actually withdraw the funds.

            Important notes:
              - The final amount due for the subscription is not known at the time of creation; it is determined only after the invoice is finalized.
              - The payment intent generated for pre-authorization cannot be reused, as the final invoice amount may exceed the authorized amount.
              - The payment intent is canceled immediately after creation, but this cancellation occurs asynchronously.
              - For these reasons, it is recommended to use a small amount (such as $1) for pre-authorization. While this does not guarantee sufficient funds for the final payment, it helps reduce the likelihood of payment errors.
          required:
            - amount_cents
            - amount_currency
          properties:
            amount_cents:
              type: integer
              example: 1000
              description: The amount of the authorization in cents.
            amount_currency:
              type: string
              example: USD
              description: The currency of the authorization.
        subscription:
          type: object
          required:
            - external_customer_id
            - plan_code
            - external_id
          properties:
            billing_entity_code:
              type: string
              example: default
              description: The code of the billing entity to be used for the subscription. If not provided, the default billing entity will be used.
            external_customer_id:
              type: string
              example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
              description: The customer external unique identifier (provided by your own application)
            plan_code:
              type: string
              example: premium
              description: The unique code representing the plan to be attached to the customer. This code must correspond to the `code` property of one of the active plans.
            name:
              type: string
              example: Repository A
              description: The display name of the subscription on an invoice. This field allows for customization of the subscription's name for billing purposes, especially useful when a single customer has multiple subscriptions using the same plan.
            external_id:
              type: string
              example: my_sub_1234567890
              description: The unique external identifier for the subscription. This identifier serves as an idempotency key, ensuring that each subscription is unique.
            billing_time:
              type: string
              description: The billing time for the subscription, which can be set as either `anniversary` or `calendar`. If not explicitly provided, it will default to `calendar`. The billing time determines the timing of recurring billing cycles for the subscription. By specifying `anniversary`, the billing cycle will be based on the specific date the subscription started (billed fully), while `calendar` sets the billing cycle at the first day of the week/month/year (billed with proration).
              example: anniversary
              enum:
                - calendar
                - anniversary
            ending_at:
              type: string
              format: date-time
              example: '2022-10-08T00:00:00Z'
              description: The effective end date of the subscription. If this field is set to null, the subscription will automatically renew. This date should be provided in ISO 8601 datetime format, and use Coordinated Universal Time (UTC).
            subscription_at:
              type: string
              format: date-time
              example: '2022-08-08T00:00:00Z'
              description: The start date for the subscription, allowing for the creation of subscriptions that can begin in the past or future. Please note that it cannot be used to update the start date of a pending subscription or schedule an upgrade/downgrade. The start_date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
            plan_overrides:
              $ref: '#/components/schemas/PlanOverridesObject'
              description: Overrides applied to the plan for this subscription. A units-only `fixed_charges` override is recorded as a per-subscription unit override without creating a plan override; any other override creates a plan override for the subscription. See `fixed_charges` for the exact rule.
            invoice_custom_section:
              $ref: '#/components/schemas/InvoiceCustomSectionInput'
            payment_method:
              $ref: '#/components/schemas/PaymentMethodReference'
              description: Optional payment method to use for processing subscription payments.
            consolidate_invoice:
              type: boolean
              default: true
              example: true
              description: |
                Defines whether this subscription should be grouped with other subscriptions of the same customer when generating recurring invoices.

                - `true` (default): the subscription is included in the customer's standard invoice grouping (by billing entity, currency and payment method).
                - `false`: the subscription is excluded from consolidation and always billed on its own dedicated invoice.
            purchase_order_number:
              type:
                - string
                - 'null'
              example: PO-123
              description: The purchase order number associated with the subscription. It will be added to invoices generated for this subscription.
            activation_rules:
              type: array
              items:
                $ref: '#/components/schemas/SubscriptionActivationRuleInput'
              description: |
                Optional list of activation rules that gate the subscription activation. When a `payment` rule is provided and the plan is paid in advance (and the subscription is not in a trial), the subscription is created in the `incomplete` state and is only activated once the gating payment succeeds. If the payment fails or the rule's `timeout_hours` elapses, the subscription is canceled.
    ApplicableUsageThreshold:
      type: object
      required:
        - threshold_display_name
        - amount_cents
        - recurring
      properties:
        threshold_display_name:
          type:
            - string
            - 'null'
          description: The display name of the usage threshold.
          example: Threshold 1
        amount_cents:
          type: integer
          description: The amount to reach to trigger a `progressive_billing` invoice.
          example: 10000
        recurring:
          type: boolean
          description: This field when set to `true` indicates that a `progressive_billing` invoice will be created every time the lifetime usage increases by the specified amount.
          example: true
    SubscriptionObjectExtended:
      allOf:
        - $ref: '#/components/schemas/SubscriptionObject'
        - type: object
          properties:
            plan:
              $ref: '#/components/schemas/PlanObject'
            applicable_usage_thresholds:
              type: array
              items:
                $ref: '#/components/schemas/ApplicableUsageThreshold'
              description: List of usage thresholds applicable to this subscription.
    SubscriptionExtended:
      type: object
      required:
        - subscription
      properties:
        subscription:
          $ref: '#/components/schemas/SubscriptionObjectExtended'
    SubscriptionUpdateInput:
      type: object
      required:
        - subscription
      properties:
        status:
          type: string
          enum:
            - active
            - pending
          example: active
          description: If the field is not defined and multiple `active` and `pending` subscriptions exists, Lago will update the `active` subscription. However, if you wish to update a `pending` subscription, please ensure that you include the `status` attribute with the `pending` value in your request body.
        subscription:
          type: object
          required:
            - ending_at
          properties:
            name:
              type:
                - string
                - 'null'
              example: Repository B
              description: The display name of the subscription on an invoice. This field allows for customization of the subscription's name for billing purposes, especially useful when a single customer has multiple subscriptions using the same plan.
            ending_at:
              type:
                - string
                - 'null'
              format: date-time
              example: '2022-10-08T00:00:00Z'
              description: The effective end date of the subscription. If this field is set to null, the subscription will automatically renew. This date should be provided in ISO 8601 datetime format, and use Coordinated Universal Time (UTC).
            subscription_at:
              type: string
              format: date-time
              example: '2022-08-08T00:00:00Z'
              description: The start date and time of the subscription. This field can only be modified for pending subscriptions that have not yet started. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
            plan_overrides:
              $ref: '#/components/schemas/PlanOverridesObject'
              description: Overrides applied to the plan for this subscription. A units-only `fixed_charges` override is recorded as a per-subscription unit override without creating a plan override; any other override creates a plan override for the subscription. See `fixed_charges` for the exact rule.
            invoice_custom_section:
              $ref: '#/components/schemas/InvoiceCustomSectionInput'
            payment_method:
              $ref: '#/components/schemas/PaymentMethodReference'
              description: Optional payment method to use for processing subscription payments.
            consolidate_invoice:
              type: boolean
              example: false
              description: |
                Defines whether this subscription should be grouped with other subscriptions of the same customer when generating recurring invoices.

                - `true`: the subscription is included in the customer's standard invoice grouping (by billing entity, currency and payment method).
                - `false`: the subscription is excluded from consolidation and always billed on its own dedicated invoice.
            billing_entity_code:
              type: string
              example: default
              description: The code of the billing entity associated with the subscription. Updates take effect on future invoices only.
            purchase_order_number:
              type:
                - string
                - 'null'
              example: PO-123
              description: The purchase order number associated with the subscription. It will be added to invoices generated for this subscription.
            activation_rules:
              type: array
              items:
                $ref: '#/components/schemas/SubscriptionActivationRuleInput'
              description: |
                Optional list of activation rules that gate the subscription activation. Activation rules can only be set or modified while the subscription is `pending` (future-dated and not yet activated); the request is rejected for `incomplete`, `active`, or `terminated` subscriptions.
    Subscription:
      type: object
      required:
        - subscription
      properties:
        subscription:
          $ref: '#/components/schemas/SubscriptionObject'
    LifetimeUsageThresholdObject:
      type: object
      required:
        - amount_cents
        - completion_ratio
        - reached_at
      properties:
        amount_cents:
          type: integer
          description: The usage threshold amount in cents.
          example: 100
        completion_ratio:
          type: number
          description: The completion ratio of the usage threshold.
          example: 0.5
        reached_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time when the usage threshold was reached. The date and time must be in ISO 8601 format.
          example: '2024-01-01T00:00:00Z'
    LifetimeUsageObject:
      type: object
      required:
        - lago_id
        - lago_subscription_id
        - external_subscription_id
        - external_historical_usage_amount_cents
        - invoiced_usage_amount_cents
        - current_usage_amount_cents
        - from_datetime
        - to_datetime
      properties:
        lago_id:
          type: string
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: Unique identifier assigned to the lifetime usage record within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the lifetime usage record within the Lago system
        lago_subscription_id:
          type: string
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
          description: Unique identifier assigned to the subscription record within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the subscription record within the Lago system
        external_subscription_id:
          type: string
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
          description: The subscription external unique identifier (provided by your own application).
        external_historical_usage_amount_cents:
          type: integer
          example: 100
          description: The historical usage amount in cents for the subscription (provided by your own application).
        invoiced_usage_amount_cents:
          type: integer
          example: 100
          description: The total invoiced usage amount in cents for the subscription.
        current_usage_amount_cents:
          type: integer
          example: 100
          description: The current usage amount in cents for the subscription on the current billing period.
        from_datetime:
          type:
            - string
            - 'null'
          format: date-time
          example: '2024-01-01T00:00:00Z'
          description: The recording start date and time of the subscription lifetime usage. The date and time must be in ISO 8601 format.
        to_datetime:
          type: string
          format: date-time
          example: '2024-12-31T23:59:59Z'
          description: The recording end date and time of the subscription lifetime usage. The date and time must be in ISO 8601 format.
        usage_thresholds:
          type: array
          description: Array of usage thresholds attached to the subscription's plan.
          items:
            $ref: '#/components/schemas/LifetimeUsageThresholdObject'
    LifetimeUsage:
      type: object
      required:
        - lifetime_usage
      properties:
        lifetime_usage:
          $ref: '#/components/schemas/LifetimeUsageObject'
    LifetimeUsageInput:
      type: object
      required:
        - lifetime_usage
      properties:
        lifetime_usage:
          type: object
          required:
            - external_historical_usage_amount_cents
          properties:
            external_historical_usage_amount_cents:
              type: integer
              example: 100
              description: The historical usage amount in cents for the subscription (provided by your own application).
    AlertObject:
      type: object
      required:
        - lago_id
        - lago_organization_id
        - external_subscription_id
        - billable_metric
        - alert_type
        - code
        - name
        - previous_value
        - last_processed_at
        - thresholds
        - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the alert, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_organization_id:
          type: string
          format: uuid
          description: Unique identifier of the organization, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_subscription_id:
          type:
            - string
            - 'null'
          description: The subscription external unique identifier (provided by your own application).
          example: sub_1234567890
        lago_wallet_id:
          type: 'null'
        wallet_code:
          type: 'null'
        billable_metric:
          $ref: '#/components/schemas/BillableMetricObject'
          description: The billable metric associated with the alert. Only for alerts based on a billable metric.
        alert_type:
          type: string
          description: The type of alert.
          enum:
            - current_usage_amount
            - billable_metric_current_usage_amount
            - billable_metric_current_usage_units
            - lifetime_usage_amount
          example: billable_metric_current_usage_amount
        code:
          type: string
          description: Unique code used to identify the alert.
          example: storage_threshold_alert
        name:
          type:
            - string
            - 'null'
          description: The name of the alert.
          example: Storage Usage Alert
        direction:
          type: string
          description: Indicates whether the alert is triggered when the monitored metric goes above or below the threshold.
          enum:
            - increasing
            - decreasing
          example: increasing
        previous_value:
          type: number
          description: When the system checked if this alert should be triggered, this value was retrieved and checked against the thresholds.
          example: 1000
        last_processed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time in UTC (ISO 8601) when the system checked if this alert should be triggered. Null until it's processed for the first time.
          example: '2025-05-19T10:04:21Z'
        thresholds:
          type: array
          description: Array of thresholds associated with the alert.
          items:
            $ref: '#/components/schemas/AlertThresholdObject'
        created_at:
          type: string
          format: date-time
          description: The date and time in UTC (ISO 8601) when the alert was created.
          example: '2025-03-20T10:00:00Z'
    Alerts:
      type: object
      required:
        - alerts
      properties:
        alerts:
          type: array
          items:
            $ref: '#/components/schemas/AlertObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    AlertCreateInput:
      type: object
      required:
        - alert
      properties:
        alert:
          allOf:
            - $ref: '#/components/schemas/AlertBaseInput'
            - type: object
              required:
                - alert_type
                - code
                - thresholds
              properties:
                alert_type:
                  type: string
                  description: The type of alert.
                  enum:
                    - current_usage_amount
                    - billable_metric_current_usage_amount
                    - billable_metric_current_usage_units
                    - lifetime_usage_amount
                  example: billable_metric_current_usage_amount
                code:
                  type: string
                  description: Unique code used to identify the alert.
                  example: storage_threshold_alert
                billable_metric_code:
                  type:
                    - string
                    - 'null'
                  description: The code of the billable metric associated with the alert. Only for alerts based on a billable metric.
                  example: storage_usage
    AlertBatchCreateInput:
      type: object
      required:
        - alerts
      properties:
        alerts:
          type: array
          description: Array of alerts to create. All alerts are created atomically - if any fail validation, none are created.
          items:
            allOf:
              - $ref: '#/components/schemas/AlertBaseInput'
              - type: object
                required:
                  - alert_type
                  - code
                  - thresholds
                properties:
                  alert_type:
                    type: string
                    description: The type of alert.
                    enum:
                      - current_usage_amount
                      - billable_metric_current_usage_amount
                      - billable_metric_current_usage_units
                      - lifetime_usage_amount
                    example: billable_metric_current_usage_amount
                  code:
                    type: string
                    description: Unique code used to identify the alert.
                    example: storage_threshold_alert
                  billable_metric_code:
                    type:
                      - string
                      - 'null'
                    description: The code of the billable metric associated with the alert. Only for alerts based on a billable metric.
                    example: storage_usage
    Alert:
      type: object
      required:
        - alert
      properties:
        alert:
          $ref: '#/components/schemas/AlertObject'
    AlertUpdateInput:
      type: object
      required:
        - alert
      properties:
        alert:
          allOf:
            - $ref: '#/components/schemas/AlertBaseInput'
            - type: object
              properties:
                billable_metric_code:
                  type:
                    - string
                    - 'null'
                  description: The code of the billable metric associated with the alert. Only for alerts based on a billable metric.
                  example: storage_usage
    SubscriptionEntitlementPrivilegeObject:
      allOf:
        - $ref: '#/components/schemas/FeaturePrivilegeObject'
        - type: object
          required:
            - value
            - plan_value
            - override_value
          properties:
            value:
              oneOf:
                - type: integer
                  description: Value for integer type privileges
                - type: boolean
                  description: Value for boolean type privileges
                - type: string
                  description: Value for string or select type privileges
              example: 10
              description: Applicable value this this subscription (override_value if set, plan_value otherwise). Type depends on the privilege's value_type.
            plan_value:
              oneOf:
                - type: integer
                  description: Value for integer type privileges
                - type: boolean
                  description: Value for boolean type privileges
                - type: string
                  description: Value for string or select type privileges
              example: 10
              description: Value assigned to this privilege in the plan. Type depends on the privilege's value_type.
            override_value:
              oneOf:
                - type: integer
                  description: Value for integer type privileges
                - type: boolean
                  description: Value for boolean type privileges
                - type: string
                  description: Value for string or select type privileges
                - type: 'null'
                  description: No override value set
              example: 10
              description: Value assigned to this subscription specifically. Type depends on the privilege's value_type. Null if no override is set.
    SubscriptionEntitlementObject:
      type: object
      required:
        - code
        - name
        - description
        - privileges
        - overrides
      properties:
        code:
          type: string
          example: seats
          description: Unique code used to identify the feature. Max 255 characters.
        name:
          type:
            - string
            - 'null'
          example: Number of seats
          description: Name of the feature. Max 255 characters.
        description:
          type:
            - string
            - 'null'
          example: Number of users of the account
          description: Description of the feature. Max 600 characters.
        privileges:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionEntitlementPrivilegeObject'
          example:
            - code: max
              name: Maximum
              value_type: integer
              config: {}
              value: 15
              plan_value: 10
              override_value: 15
            - code: max_admins
              name: Max Admins
              value_type: integer
              config: {}
              value: 5
              plan_value: 5
              override_value: null
            - code: root
              name: Allow root user
              value_type: boolean
              config: {}
              value: true
              plan_value: true
              override_value: null
            - code: provider
              name: SSO Provider
              value_type: select
              value: okta
              plan_value: google
              override_value: okta
              config:
                select_options:
                  - google
                  - okta
          description: Privileges associated with this feature. Each privilege shows the plan value and any subscription override.
        overrides:
          type: object
          additionalProperties: true
          example:
            max: 15
            provider: okta
    SubscriptionEntitlements:
      type: object
      required:
        - entitlements
      properties:
        entitlements:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionEntitlementObject'
    SubscriptionEntitlement:
      type: object
      required:
        - entitlement
      properties:
        entitlement:
          $ref: '#/components/schemas/SubscriptionEntitlementObject'
    SubscriptionChargeOverride:
      type: object
      required:
        - charge
      properties:
        charge:
          $ref: '#/components/schemas/ChargeOverridableInput'
    SubscriptionFixedChargeOverride:
      type: object
      required:
        - fixed_charge
      properties:
        fixed_charge:
          $ref: '#/components/schemas/FixedChargeOverridableInput'
    TaxesPaginated:
      type: object
      required:
        - taxes
        - meta
      properties:
        taxes:
          type: array
          items:
            $ref: '#/components/schemas/TaxObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    TaxBaseInput:
      type: object
      properties:
        name:
          type: string
          description: Name of the tax.
          example: TVA
        code:
          type: string
          description: Unique code used to identify the tax associated with the API request.
          example: french_standard_vat
        rate:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: The percentage rate of the tax
          example: '20.0'
        description:
          type:
            - string
            - 'null'
          description: Internal description of the taxe
          example: French standard VAT
        applied_to_organization:
          type: boolean
          deprecated: true
          description: '**Deprecated.** This field will be removed in a future version. When set to true, it applies the tax to the organization''s default billing entity. To apply or remove a tax from any billing entity (including the default one), please use the `PUT /billing_entities/:code` endpoint instead.'
          example: true
    TaxCreateInput:
      type: object
      required:
        - tax
      properties:
        tax:
          $ref: '#/components/schemas/TaxBaseInput'
          required:
            - name
            - code
            - rate
    Tax:
      type: object
      required:
        - tax
      properties:
        tax:
          $ref: '#/components/schemas/TaxObject'
    TaxUpdateInput:
      type: object
      required:
        - tax
      properties:
        tax:
          $ref: '#/components/schemas/TaxBaseInput'
    WalletTransactionCreateInput:
      type: object
      required:
        - wallet_transaction
      properties:
        wallet_transaction:
          type: object
          required:
            - wallet_id
          properties:
            wallet_id:
              type: string
              format: uuid
              description: Unique identifier assigned to the wallet within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the wallet's record within the Lago system.
              example: 1a901a90-1a90-1a90-1a90-1a901a901a90
            name:
              type:
                - string
                - 'null'
              description: |
                The name of the wallet transaction. It will appear on the invoice as the label for the fee. If not set, the label on the invoice will fallback to either `Prepaid credits - {{wallet_name}}` if the wallet name is set, or `Prepaid credits`.

                Note that this name will apply to all transactions (`paid_credits`, `granted_credits` and `voided_credits`) created by this action.
              example: Tokens for models 'high-fidelity-boost'
            paid_credits:
              type:
                - string
                - 'null'
              pattern: ^[0-9]+.?[0-9]*$
              description: The number of paid credits.
              example: '20.0'
            granted_credits:
              type:
                - string
                - 'null'
              pattern: ^[0-9]+.?[0-9]*$
              description: The number of free granted credits.
              example: '10.0'
            voided_credits:
              type:
                - string
                - 'null'
              pattern: ^[0-9]+.?[0-9]*$
              description: The number of voided credits.
              example: '5.0'
            invoice_requires_successful_payment:
              type: boolean
              description: A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false.
              example: false
            ignore_paid_top_up_limits:
              type: boolean
              description: When true, allows topping up the wallet with transactions that exceed the paid top-up limits. Defaults to false.
              example: false
            purchase_order_number:
              type:
                - string
                - 'null'
              example: PO-123
              description: The purchase order number associated with this wallet transaction. It will be added to invoices generated for the resulting wallet top-up. If not set, falls back to the wallet's `purchase_order_number`.
            invoice_custom_section:
              $ref: '#/components/schemas/InvoiceCustomSectionInput'
            payment_method:
              $ref: '#/components/schemas/PaymentMethodReference'
              description: Optional payment method to use for processing the wallet transaction payment.
            metadata:
              type:
                - array
                - 'null'
              description: This optional field allows you to store a list of key-value pairs that hold additional information or custom attributes related to the data.
              items:
                type: object
                properties:
                  key:
                    type: string
                    description: The unique identifier for the attribute.
                  value:
                    type: string
                    description: The value associated with the key.
              example:
                - key: example key
                  value: example value
                - key: another key
                  value: another value
    WalletTransactionObject:
      type: object
      required:
        - lago_id
        - lago_wallet_id
        - lago_invoice_id
        - lago_credit_note_id
        - lago_voided_invoice_id
        - status
        - source
        - transaction_status
        - transaction_type
        - credit_amount
        - amount
        - remaining_amount_cents
        - remaining_credit_amount
        - priority
        - invoice_requires_successful_payment
        - settled_at
        - failed_at
        - created_at
        - metadata
        - name
        - payment_method
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the wallet transaction within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the wallet transaction's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_wallet_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the wallet within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the wallet's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_invoice_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Unique identifier assigned to the invoice associated with this wallet transaction. This ID is exclusively created by Lago and serves as a unique identifier for the invoice's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_credit_note_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Unique identifier of the credit note associated with this wallet transaction. This ID is exclusively created by Lago and serves as a unique identifier for the invoice's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_voided_invoice_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Unique identifier of the invoice that was voided and triggered the creation of this inbound wallet transaction. Only present for inbound transactions on traceable wallets that were created as a result of an invoice void.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        status:
          type: string
          enum:
            - pending
            - settled
            - failed
          description: The status of the wallet transaction. Possible values are `pending`, `settled` or `failed`.
          example: settled
        source:
          type: string
          enum:
            - manual
            - interval
            - threshold
          description: The source field represents the origin or trigger of the wallet transaction. Possible values are `manual`, `interval`, `threshold`
          example: manual
        transaction_status:
          type: string
          enum:
            - purchased
            - granted
            - voided
            - invoiced
          description: The transaction status of the wallet transaction. Possible values are `purchased` (with pending or settled status), `granted` (without invoice_id), `voided` or `invoiced`.
          example: purchased
        transaction_type:
          type: string
          enum:
            - inbound
            - outbound
          description: The type of transaction. Possible values are `inbound` (increasing the balance) or `outbound` (decreasing the balance).
          example: inbound
        amount:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: The amount of credits based on the rate and the currency.
          example: '10.0'
        credit_amount:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: The number of credits used in the wallet transaction.
          example: '100.0'
        invoice_requires_successful_payment:
          type: boolean
          description: A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false.
          example: false
        metadata:
          type: array
          description: This field allows you to store a list of key-value pairs that hold additional information or custom attributes related to the data.
          items:
            type: object
            properties:
              key:
                type: string
                description: The unique identifier for the attribute.
              value:
                type: string
                description: The value associated with the key.
          example:
            - key: example key
              value: example value
            - key: another key
              value: another value
        remaining_amount_cents:
          type:
            - integer
            - 'null'
          description: The remaining unconsumed amount of an inbound wallet transaction, expressed in cents. Only present for inbound transactions on traceable wallets. Tracks how much of the original credited amount has not yet been consumed by outbound transactions.
          example: 5000
        remaining_credit_amount:
          type:
            - string
            - 'null'
          pattern: ^[0-9]+.?[0-9]*$
          description: The remaining unconsumed amount of an inbound wallet transaction, expressed in credits. Only present for inbound transactions on traceable wallets.
          example: '5.0'
        priority:
          type: integer
          description: The priority of the wallet transaction, used to determine the order in which inbound transactions are consumed. Lower values are consumed first.
          example: 50
        settled_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date when wallet transaction is settled, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
          example: '2022-04-29T08:59:51Z'
        failed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date when the wallet transaction failed, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
          example: '2022-04-29T08:59:51Z'
        created_at:
          type: string
          format: date-time
          description: The date of the wallet transaction creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
          example: '2022-04-29T08:59:51Z'
        name:
          type:
            - string
            - 'null'
          description: The name of the wallet transaction. It will appear on the invoice as the label for the fee. If not set, the label on the invoice will fallback to either `Prepaid credits - {{wallet_name}}` if the wallet name is set, or `Prepaid credits`.
          example: Tokens for models 'high-fidelity-boost'
        applied_invoice_custom_sections:
          description: The invoice custom sections applied to invoices generated by this wallet transaction.
          type: array
          items:
            $ref: '#/components/schemas/AppliedInvoiceCustomSectionObject'
        payment_method:
          $ref: '#/components/schemas/PaymentMethodReference'
          description: The payment method assigned to this wallet transaction for processing the payment.
        purchase_order_number:
          type:
            - string
            - 'null'
          example: PO-123
          description: The purchase order number associated with this wallet transaction. It will be added to invoices generated for the resulting wallet top-up. If not set, falls back to the wallet's `purchase_order_number`.
    WalletTransactions:
      type: object
      required:
        - wallet_transactions
      properties:
        wallet_transactions:
          type: array
          items:
            $ref: '#/components/schemas/WalletTransactionObject'
    WalletTransactionPaymentUrl:
      type: object
      required:
        - lago_wallet_transaction_id
        - lago_customer_id
        - external_customer_id
        - payment_provider
      description: .
      properties:
        wallet_transaction_payment_details:
          type: object
          properties:
            lago_customer_id:
              type: string
              example: 1a901a90-1a90-1a90-1a90-1a901a901a90
              description: Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer's record within the Lago system
            lago_wallet_transaction_id:
              type: string
              example: 1e501a90-1a90-1a90-1a90-1a901a901a80
              description: Unique identifier assigned to the wallet transaction within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the wallet transaction's record within the Lago system
            external_customer_id:
              type: string
              example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
              description: The customer external unique identifier (provided by your own application)
            payment_provider:
              type: string
              example: stripe
              description: The Payment Provider name linked to the Customer.
            payment_url:
              type: string
              example: https://foo.bar
              description: The generated Payment URL for the Wallet transaction.
    WalletTransactionConsumptionObject:
      type: object
      required:
        - lago_id
        - amount_cents
        - credit_amount
        - created_at
        - wallet_transaction
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the wallet transaction consumption within the Lago application.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        amount_cents:
          type: integer
          description: The amount consumed from the inbound wallet transaction, expressed in cents.
          example: 5000
        credit_amount:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: The amount consumed from the inbound wallet transaction, expressed in credits.
          example: '5.0'
        created_at:
          type: string
          format: date-time
          description: The date of the consumption record creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
          example: '2022-04-29T08:59:51Z'
        wallet_transaction:
          $ref: '#/components/schemas/WalletTransactionObject'
    WalletTransactionConsumptions:
      type: object
      required:
        - wallet_transaction_consumptions
      properties:
        wallet_transaction_consumptions:
          type: array
          items:
            $ref: '#/components/schemas/WalletTransactionConsumptionObject'
    WalletTransactionConsumptionsPaginated:
      allOf:
        - $ref: '#/components/schemas/WalletTransactionConsumptions'
        - type: object
          required:
            - meta
          properties:
            meta:
              $ref: '#/components/schemas/PaginationMeta'
    WalletTransactionFundingObject:
      type: object
      required:
        - lago_id
        - amount_cents
        - credit_amount
        - created_at
        - wallet_transaction
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the wallet transaction funding within the Lago application.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        amount_cents:
          type: integer
          description: The amount funded from the inbound wallet transaction, expressed in cents.
          example: 5000
        credit_amount:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: The amount funded from the inbound wallet transaction, expressed in credits.
          example: '5.0'
        created_at:
          type: string
          format: date-time
          description: The date of the funding record creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
          example: '2022-04-29T08:59:51Z'
        wallet_transaction:
          $ref: '#/components/schemas/WalletTransactionObject'
    WalletTransactionFundings:
      type: object
      required:
        - wallet_transaction_fundings
      properties:
        wallet_transaction_fundings:
          type: array
          items:
            $ref: '#/components/schemas/WalletTransactionFundingObject'
    WalletTransactionFundingsPaginated:
      allOf:
        - $ref: '#/components/schemas/WalletTransactionFundings'
        - type: object
          required:
            - meta
          properties:
            meta:
              $ref: '#/components/schemas/PaginationMeta'
    WalletTransactionsPaginated:
      allOf:
        - $ref: '#/components/schemas/WalletTransactions'
        - type: object
          required:
            - meta
          properties:
            meta:
              $ref: '#/components/schemas/PaginationMeta'
    WebhookPublicKeyObject:
      type: object
      required:
        - public_key
      properties:
        public_key:
          type: string
          description: Base64-encoded public key used to verify webhook signatures.
          example: MEgCQQCo9+BpMRYQ/dL3DS2CyJxRF+j6ctbT3/Qp84+KeFhnii7NT7fELilKUSnxS30WAvQCCo2yU1orfgqr41mM70MBAgMBAAE=
    WebhookPublicKey:
      type: object
      required:
        - webhook
      properties:
        webhook:
          $ref: '#/components/schemas/WebhookPublicKeyObject'
    WebhookEndpointObject:
      type: object
      required:
        - lago_id
        - lago_organization_id
        - webhook_url
        - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the wallet within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the webhook endpoint's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_organization_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the organization attached to the webhook endpoint within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the organization's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        webhook_url:
          type: string
          description: The URL of the webhook endpoint.
          example: https://foo.bar
        signature_algo:
          type: string
          description: The signature algo for the webhook.
          example: hmac
          enum:
            - jwt
            - hmac
        name:
          type:
            - string
            - 'null'
          description: The name of the webhook.
          example: EC2-production
        event_types:
          type:
            - array
            - 'null'
          description: A list of event types that will trigger the webhook. Passing null means that all event types will be sent.
          items:
            type: string
          example:
            - invoice.voided
            - customer.created
        created_at:
          type: string
          format: date-time
          description: The date of the webhook endpoint creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
          example: '2022-04-29T08:59:51Z'
    WebhookEndpointsPaginated:
      type: object
      required:
        - webhook_endpoints
        - meta
      properties:
        webhook_endpoints:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEndpointObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    WebhookEndpointCreateInput:
      type: object
      properties:
        webhook_endpoint:
          type: object
          required:
            - webhook_url
          properties:
            webhook_url:
              type: string
              description: The URL of the webhook endpoint.
              example: https://foo.bar
            signature_algo:
              type:
                - string
                - 'null'
              description: The signature used for the webhook. If no value is passed,
              example: hmac
              enum:
                - jwt
                - hmac
                - null
            name:
              type:
                - string
                - 'null'
              description: The name of the webhook.
              example: EC2-production
            event_types:
              type:
                - array
                - 'null'
              description: A list of event types that will trigger the webhook. Passing null means that all event types will be sent.
              items:
                type: string
              example:
                - invoice.voided
                - customer.created
    WebhookEndpoint:
      type: object
      required:
        - webhook_endpoint
      properties:
        webhook_endpoint:
          $ref: '#/components/schemas/WebhookEndpointObject'
    WebhookEndpointUpdateInput:
      type: object
      properties:
        webhook_endpoint:
          type: object
          required:
            - webhook_url
          properties:
            webhook_url:
              type: string
              description: The URL of the webhook endpoint.
              example: https://foo.bar
            signature_algo:
              type:
                - string
                - 'null'
              description: The signature used for the webhook. If no value is passed,
              example: hmac
              enum:
                - jwt
                - hmac
                - null
            name:
              type:
                - string
                - 'null'
              description: The name of the webhook.
              example: EC2-production
            event_types:
              type:
                - array
                - 'null'
              description: A list of event types that will trigger the webhook. Passing null means that all event types will be sent.
              items:
                type: string
              example:
                - invoice.voided
                - customer.created
    TriggeredAlertObject:
      type: object
      required:
        - lago_id
        - lago_organization_id
        - lago_alert_id
        - lago_subscription_id
        - external_subscription_id
        - external_customer_id
        - billable_metric_code
        - alert_type
        - alert_code
        - alert_name
        - current_value
        - previous_value
        - triggered_at
        - crossed_thresholds
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the alert, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_organization_id:
          type: string
          format: uuid
          description: Unique identifier of the organization, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_alert_id:
          type: string
          format: uuid
          description: Unique identifier of the alert, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_subscription_id:
          type: string
          format: uuid
          description: Unique identifier of the subscription, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_subscription_id:
          type: string
          description: The subscription external unique identifier (provided by your own application).
          example: sub_1234567890
        external_customer_id:
          type: string
          description: The customer external unique identifier (provided by your own application).
          example: cust_1234567890
        billable_metric_code:
          type:
            - string
            - 'null'
          description: The code of the billable metric associated with the alert. Only for alerts based on a billable metric.
          example: storage_usage
        alert_type:
          type: string
          description: The type of alert triggered.
          enum:
            - current_usage_amount
            - billable_metric_current_usage_amount
            - billable_metric_current_usage_units
            - lifetime_usage_amount
          example: billable_metric_current_usage_amount
        alert_code:
          type: string
          description: Unique code used to identify the alert triggered.
          example: storage_threshold_alert
        alert_name:
          type:
            - string
            - 'null'
          description: The name of the alert triggered.
          example: Storage Usage Alert
        current_value:
          type: number
          description: When the system checked if this alert should be triggered, this value was retrieved and checked if any threshold were crossed between this value and previous value.
          example: 1200
        previous_value:
          type: number
          description: During the previous run, this value was retrieved.
          example: 900
        triggered_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time in UTC (ISO 8601) when the system triggered the alert.
          example: '2025-05-19T10:04:21Z'
        crossed_thresholds:
          type: array
          description: Array of thresholds crossed. All the recurring threshold values are present.
          items:
            $ref: '#/components/schemas/AlertThresholdObject'
    CustomerIntegratrionErrorObject:
      type: object
      required:
        - lago_customer_id
        - external_customer_id
        - accounting_provider
        - accounting_provider_code
        - provider_error
      properties:
        lago_customer_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_customer_id:
          type: string
          description: The customer external unique identifier (provided by your own application)
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        accounting_provider:
          type: string
          enum:
            - anrok
            - hubspot
            - netsuite
            - okta
            - salesforce
            - xero
          description: The type of accounting provider code
          example: anrok
        accounting_provider_code:
          type: string
          description: Code of the accounting provider
          example: Netsuite Prod
        provider_error:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
    CustomerPaymentProviderErrorObject:
      type: object
      required:
        - lago_customer_id
        - external_customer_id
        - payment_provider
        - payment_provider_code
        - provider_error
      properties:
        lago_customer_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_customer_id:
          type: string
          description: The customer external unique identifier (provided by your own application)
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        payment_provider:
          type: string
          enum:
            - adyen
            - cashfree
            - gocardless
            - stripe
          description: The type of payment provider
          example: stripe
        payment_provider_code:
          type: string
          description: Code of the payment provider
          example: Stripe Prod
        provider_error:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
    CustomerTaxProviderErrorObject:
      type: object
      required:
        - lago_customer_id
        - external_customer_id
        - tax_provider
        - tax_provider_code
        - provider_error
      properties:
        lago_customer_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_customer_id:
          type: string
          description: The customer external unique identifier (provided by your own application)
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        tax_provider:
          type: string
          enum:
            - anrock
            - hubspot
            - netsuite
            - okta
            - salesforce
            - xero
          description: The type of tax provider
          example: anrock
        tax_provider_code:
          type: string
          description: Code of the tax provider
          example: Stripe Prod
        provider_error:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
    CustomerViesCheckObject:
      allOf:
        - $ref: '#/components/schemas/CustomerBaseObject'
        - type: object
          properties:
            vies_check:
              type: object
              properties:
                valid:
                  type: boolean
                  description: Whether the VIES check was successful
                  example: true
    CreditNotePaymentProviderRefundError:
      type: object
      required:
        - lago_credit_note_id
        - lago_customer_id
        - external_customer_id
        - payment_provider
      properties:
        lago_credit_note_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the credit note within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the credit note record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_customer_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_customer_id:
          type: string
          description: The customer external unique identifier (provided by your own application)
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        provider_customer_id:
          type: string
          description: Unique identifier of the customer within the payment provider
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        payment_provider:
          type: string
          enum:
            - adyen
            - cashfree
            - gocardless
            - stripe
          description: The type of payment provider code
          example: stripe
        payment_provider_code:
          type: string
          description: Code of the payment provider
          example: Stripe Prod
        provider_error:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
    OverdueBalancePerCurrencyObject:
      type: object
      required:
        - amount_cents
        - currency
      properties:
        amount_cents:
          type: integer
          description: The amount of the overdue balance for this currency, expressed in cents.
          example: 120
        currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of the overdue balance.
          example: EUR
    DunningCampaignFinishedObject:
      type: object
      required:
        - external_customer_id
        - dunning_campaign_code
        - overdue_balance_cents
        - overdue_balance_currency
      properties:
        external_customer_id:
          type: string
          description: The customer external unique identifier (provided by your own application).
          example: cus_0987654321
        dunning_campaign_code:
          type: string
          description: Identifier of the dunning campaign.
          example: dun_code_1234
        overdue_balance_cents:
          type: integer
          description: The amount of the overdue balance, expressed in cents.
          example: 120
        overdue_balance_currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of the balance.
          example: EUR
        overdue_balances:
          type: array
          description: Overdue balance broken down per currency.
          items:
            $ref: '#/components/schemas/OverdueBalancePerCurrencyObject'
    EventErrorsObject:
      type: object
      required:
        - status
        - error
        - message
        - event
      properties:
        status:
          type: integer
          description: HTTP status code. It will always be 422
          example: 422
        error:
          type: string
          description: HTTP error description. It will always be "Unprocessable entity"
          example: Unprocessable entity
        message:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
        event:
          $ref: '#/components/schemas/EventObject'
    EventsErrorsObject:
      type: object
      required:
        - invalid_code
        - missing_aggregation_property
        - invalid_filter_values
        - missing_group_key
      properties:
        invalid_code:
          type: array
          items:
            type: string
          description: List of event transaction_id with an invalid code
          example:
            - transaction_1234567890
        missing_aggregation_property:
          type: array
          items:
            type: string
          description: List of event transaction_id with a missing aggregation property
          example:
            - transaction_1234567890
        invalid_filter_values:
          type: array
          items:
            type: string
          description: List of event transaction_id with invalid filter values
          example:
            - transaction_1234567890
        missing_group_key:
          type: array
          items:
            type: string
          description: '**Deprecated.** List of event transaction_id with a missing group key.'
          deprecated: true
    FeeTaxProviderErrorObject:
      type: object
      required:
        - tax_provider_code
        - lago_charge_id
        - event_transaction_id
        - provider_error
      properties:
        tax_provider_code:
          type: string
          description: Code of the tax provider
          example: Stripe Prod
        lago_charge_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Unique identifier assigned to the charge that the fee belongs to
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        event_transaction_id:
          type:
            - string
            - 'null'
          description: Unique identifier assigned to the transaction. This field is specifically displayed when the fee type is `charge`.
          example: transaction_1234567890
        provider_error:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
    InvoicePaymentDisputeLostObject:
      allOf:
        - $ref: '#/components/schemas/InvoiceObjectExtended'
        - type: object
          properties:
            provider_error:
              oneOf:
                - type: string
                - type: object
                  additionalProperties: true
    InvoicePaymentFailureObject:
      type: object
      required:
        - lago_invoice_id
        - lago_customer_id
        - external_customer_id
        - payment_provider
      properties:
        lago_invoice_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the invoice within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the invoice's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_customer_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_customer_id:
          type: string
          description: The customer external unique identifier (provided by your own application)
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        provider_customer_id:
          type: string
          description: Unique identifier of the customer within the payment provider
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        payment_provider:
          type: string
          enum:
            - adyen
            - cashfree
            - gocardless
            - stripe
          description: The type of payment provider code
          example: stripe
        payment_provider_code:
          type: string
          description: Code of the payment provider
          example: Stripe Prod
        provider_error:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
    IntegrationProviderErrorObject:
      type: object
      required:
        - lago_integration_id
        - provider
        - provider_code
        - provider_error
      properties:
        lago_integration_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the integration within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the integration's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        provider:
          type: string
          description: The type of integration provider
          example: netsuite
        provider_code:
          type: string
          example: netsuite-eu-1
          description: Unique code used to identify an integration connection.
        provider_error:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
    PaymentProviderErrorObject:
      type: object
      required:
        - lago_payment_provider_id
        - payment_provider_name
        - payment_provider_code
        - provider_error
        - source
      properties:
        lago_payment_provider_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the payment provider within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the payment provider's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        payment_provider_name:
          type: string
          description: The name of payment provider
          example: Stripe Prod
        payment_provider_code:
          type: string
          description: Code of the payment provider
          example: stripe
        source:
          type: string
          enum:
            - stripe
          description: The source of the error
          example: stripe
        action:
          type: string
          enum:
            - payment_provider.register_webhook
          description: The action that was being performed when the error occurred
          example: payment_provider.register_webhook
        provider_error:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
    PaymentRequestPaymentFailureObject:
      type: object
      required:
        - lago_payment_request_id
        - lago_invoice_ids
        - lago_customer_id
        - external_customer_id
        - payment_provider
      properties:
        lago_payment_request_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the payment request within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the payment request record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_invoice_ids:
          type: array
          items:
            type: string
            format: uuid
          description: List of unique identifiers assigned to the invoices within the Lago application. These IDs are exclusively created by Lago and serve as unique identifiers for the invoices records within the Lago system.
          example:
            - 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_customer_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_customer_id:
          type: string
          description: The customer external unique identifier (provided by your own application)
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        provider_customer_id:
          type: string
          description: Unique identifier of the customer within the payment provider
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        payment_provider:
          type: string
          enum:
            - adyen
            - cashfree
            - gocardless
            - stripe
          description: The type of payment provider code
          example: stripe
        payment_provider_code:
          type: string
          description: Code of the payment provider
          example: Stripe Prod
        provider_error:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
    SubscriptionWithCustomerObject:
      allOf:
        - $ref: '#/components/schemas/SubscriptionObject'
        - type: object
          required:
            - plan
            - customer
          properties:
            plan:
              $ref: '#/components/schemas/PlanObject'
            customer:
              $ref: '#/components/schemas/CustomerObject'
    SubscriptionWithThresholdObject:
      allOf:
        - $ref: '#/components/schemas/SubscriptionObject'
        - type: object
          required:
            - plan
            - customer
            - usage_threshold
          properties:
            plan:
              $ref: '#/components/schemas/PlanObject'
            customer:
              $ref: '#/components/schemas/CustomerObject'
            usage_threshold:
              $ref: '#/components/schemas/UsageThresholdObject'
            applicable_usage_thresholds:
              type: array
              items:
                $ref: '#/components/schemas/ApplicableUsageThreshold'
              description: List of usage thresholds applicable to this subscription.
    WalletTransactionObjectExtended:
      allOf:
        - $ref: '#/components/schemas/WalletTransactionObject'
        - type: object
          properties:
            wallet:
              $ref: '#/components/schemas/WalletObject'
    WalletTransactionPaymentFailureObject:
      type: object
      required:
        - lago_wallet_transaction_id
        - lago_customer_id
        - external_customer_id
        - payment_provider
      properties:
        lago_wallet_transaction_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the wallet transaction within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the wallet transaction's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_customer_id:
          type: string
          format: uuid
          description: Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer's record within the Lago system.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_customer_id:
          type: string
          description: The customer external unique identifier (provided by your own application)
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        provider_customer_id:
          type: string
          description: Unique identifier of the customer within the payment provider
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
        payment_provider:
          type: string
          enum:
            - adyen
            - cashfree
            - gocardless
            - stripe
          description: The type of payment provider code
          example: stripe
        payment_provider_code:
          type: string
          description: Code of the payment provider
          example: Stripe Prod
        provider_error:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
    CustomerPaymentProvidernErrorObject:
      $ref: '#/components/schemas/CustomerPaymentProviderErrorObject'
  responses:
    Unauthorized:
      description: Unauthorized error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorUnauthorized'
    UnprocessableEntity:
      description: Unprocessable entity error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorUnprocessableEntity'
    BadRequest:
      description: Bad Request error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorBadRequest'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorForbidden'
    NotFound:
      description: Not Found error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorNotFound'
    NotAllowed:
      description: Not Allowed error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorNotAllowed'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer