openapi.yaml

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.17.1
  license:
    name: AGPLv3
    identifier: AGPLv3
  contact:
    email: tech@getlago.com
externalDocs:
  description: Lago Github
  url: 'https://github.com/getlago'
servers:
  - url: 'https://api.getlago.com/api/v1'
    description: US Lago cluster
  - url: 'https://api.eu.getlago.com/api/v1'
    description: EU Lagos cluster
security:
  - bearerAuth: []
tags:
  - name: analytics
    description: Everything about Analytics
  - name: billable_metrics
    description: Everything about Billable metric collection
    externalDocs:
      description: Find out more
      url: 'https://doc.getlago.com/docs/api/billable_metrics/billable-metric-object'
  - name: customers
    description: Everything about Customer collection
    externalDocs:
      description: Find out more
      url: 'https://doc.getlago.com/docs/api/customers/customer-object'
  - name: plans
    description: Everything about Plan collection
    externalDocs:
      description: Find out more
      url: 'https://doc.getlago.com/docs/api/plans/plan-object'
  - name: subscriptions
    description: Everything about Subscription collection
    externalDocs:
      description: Find out more
      url: 'https://doc.getlago.com/docs/api/subscriptions/subscription-object'
  - name: events
    description: Everything about Event collection
    externalDocs:
      description: Find out more
      url: 'https://doc.getlago.com/docs/api/events/event-object'
  - name: organizations
    description: Everything about Organization collection
    externalDocs:
      description: Find out more
      url: 'https://doc.getlago.com/docs/api/organizations/organization-object'
  - name: taxes
    description: Everything about Tax collection
    externalDocs:
      description: Find out more
      url: 'https://doc.getlago.com/docs/api/taxes/tax-object'
  - name: coupons
    description: Everything about Coupon collection
    externalDocs:
      description: Find out more
      url: 'https://doc.getlago.com/docs/api/coupons/coupon-object'
  - name: add_ons
    description: Everything about Add-on collection
    externalDocs:
      description: Find out more
      url: 'https://doc.getlago.com/docs/api/add_ons/add-on-object'
  - name: fees
    description: Everything about Fees
    externalDocs:
      description: Find out more
      url: 'https://doc.getlago.com/docs/api/invoices/invoice-object#fee-object'
  - name: invoices
    description: Everything about Invoice collection
    externalDocs:
      description: Find out more
      url: 'https://doc.getlago.com/docs/api/invoices/invoice-object'
  - name: wallets
    description: Everything about Wallet collection
    externalDocs:
      description: Find out more
      url: 'https://doc.getlago.com/docs/api/wallets/wallet-object'
  - name: credit_notes
    description: Everything about Credit notes collection
    externalDocs:
      description: Find out more
      url: 'https://doc.getlago.com/docs/api/credit_notes/credit-note-object'
  - name: webhooks
    description: Everything about Webhooks
    externalDocs:
      description: Find out more
      url: 'https://doc.getlago.com/docs/api/webhooks/message-signature#1-retrieve-the-public-key'
  - name: webhook_endpoints
    description: Everything about Webhook Endpoints
    externalDocs:
      description: Find out more
      url: 'https://doc.getlago.com/docs/api/webhook_endpoints/webhook-endpoint-object'
  - name: payment_requests
    description: Everything about PaymentRequests
    externalDocs:
      description: Find out more
      url: 'https://doc.getlago.com/docs/api/payment_requests/payment_request-object'
paths:
  /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'
        '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'
  '/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'
        '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'
        '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'
        '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'
  /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 `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'
  /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'
  /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
      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'
  /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/CreditNote'
        '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
      responses:
        '200':
          description: Credit notes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditNotes'
        '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/CreditNote'
        '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/CreditNote'
        '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/CreditNote'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/NotAllowed'
  /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'
      responses:
        '200':
          description: List of customers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomersPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  '/customers/{external_id}':
    parameters:
      - name: external_id
        in: path
        description: External ID of the existing customer
        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/{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:
        - 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: 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}/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}/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
      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}/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
                description: .
                properties:
                  customer:
                    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
                      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.
                      checkout_url:
                        type: string
                        example: 'https://foo.bar'
                        description: The new generated Payment Provider Checkout URL for the Customer.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /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/Event'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '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
          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:
                type: object
                required:
                  - events
                  - meta
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/EventObject'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /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
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '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'
        '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.
      operationId: findEvent
      responses:
        '200':
          description: Event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '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` or `subscription`.'
          required: false
          explode: true
          schema:
            type: string
            enum:
              - charge
              - add_on
              - subscription
              - credit
              - instant_charge
            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: 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: 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` or `advance_charges`'
          required: false
          explode: true
          schema:
            type: string
            enum:
              - subscription
              - add_on
              - credit
              - one_off
              - advance_charges
      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'
  '/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:
                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.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  '/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
      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. You can void an invoice only when it''s in a `finalized` status, and the payment status is not `succeeded`.'
      parameters:
        - $ref: '#/components/parameters/lago_invoice_id'
      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_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:
              type: object
              required:
                - payment_request
              properties:
                payment_request:
                  type: object
                  required:
                    - email
                    - external_customer_id
                    - lago_invoice_ids
                  properties:
                    customer_external_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.
        required: true
      responses:
        '200':
          description: PaymentRequest created
          content:
            application/json:
              schema:
                type: object
                required:
                  - payment_request
                properties:
                  payment_request:
                    $ref: '#/components/schemas/PaymentRequestObject'
        '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/external_customer_id'
      responses:
        '200':
          description: PaymentRequests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequestsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /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'
  /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/Subscription'
        '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'
        - 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: 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
      responses:
        '200':
          description: List of subscriptions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  '/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
      responses:
        '200':
          description: Subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '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
      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
      responses:
        '200':
          description: Subscription terminated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/NotAllowed'
  '/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: Retrive 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'
  /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
                    customers_count: 0
                    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
                    customers_count: 0
                    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'
        '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'
        - 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
      responses:
        '200':
          description: Wallets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  '/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'
        '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'
        '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'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/NotAllowed'
  /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'
        '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'
        '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
      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'
  /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'
components:
  parameters:
    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
    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
    months:
      name: months
      in: query
      description: Show data only for given number of months.
      required: false
      explode: true
      schema:
        type: integer
        example: 12
    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
  schemas:
    AddOnBaseInput:
      type: object
      properties:
        name:
          type: string
          description: The name of the add-on.
          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)
        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
          nullable: true
          description: The description of the add-on.
          example: Implementation fee for new customers.
        tax_codes:
          type: array
          items:
            type: string
          description: List of unique code used to identify the taxes.
          example:
            - french_standard_vat
    AddOnCreateInput:
      type: object
      required:
        - add_on
      properties:
        add_on:
          $ref: '#/components/schemas/AddOnBaseInput'
          required:
            - name
            - code
            - amount_cents
            - amount_currency
    AddOnObject:
      type: object
      required:
        - lago_id
        - name
        - code
        - amount_cents
        - amount_currency
        - 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
          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
          nullable: true
          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'
    AddOn:
      type: object
      required:
        - add_on
      properties:
        add_on:
          $ref: '#/components/schemas/AddOnObject'
    AddOnsPaginated:
      type: object
      required:
        - add_ons
        - meta
      properties:
        add_ons:
          type: array
          items:
            $ref: '#/components/schemas/AddOnObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    AddOnUpdateInput:
      type: object
      required:
        - add_on
      properties:
        add_on:
          $ref: '#/components/schemas/AddOnBaseInput'
    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
    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
    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
    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
    AppliedCoupon:
      type: object
      required:
        - applied_coupon
      properties:
        applied_coupon:
          $ref: '#/components/schemas/AppliedCouponObject'
    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
              enum:
                - once
                - recurring
                - forever
              nullable: true
              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
              nullable: true
              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
              nullable: true
              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/Currency'
              nullable: true
              description: The currency of the coupon. This field is required only for coupon with `fixed_amount` type.
              example: EUR
            percentage_rate:
              type: string
              pattern: '^[0-9]+.?[0-9]*$'
              nullable: true
              description: The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type.
              example: null
    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
        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
          nullable: true
          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
          nullable: true
          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/Currency'
          nullable: true
          description: The currency of the coupon. This field is required only for coupon with `fixed_amount` type.
          example: EUR
        percentage_rate:
          type: string
          pattern: '^[0-9]+.?[0-9]*$'
          nullable: true
          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
          nullable: true
          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
          nullable: true
          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
          format: date-time
          nullable: true
          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
          format: date-time
          nullable: true
          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'
    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'
    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.
        usage_threshold:
          $ref: '#/components/schemas/UsageThresholdObject'
    BaseAppliedTax:
      type: object
      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
          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
        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'
    BillableMetric:
      type: object
      required:
        - billable_metric
      properties:
        billable_metric:
          $ref: '#/components/schemas/BillableMetricObject'
    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
          example: GB of storage used in my application
          description: Internal description of the billable metric.
          nullable: true
        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
          enum:
            - ceil
            - floor
            - round
          nullable: true
          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
          example: 2
          nullable: true
          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
          example: gb
          description: Property of the billable metric used for aggregating usage data. This field is not required for `count_agg`.
          nullable: true
        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
          enum:
            - seconds
          nullable: true
          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'
    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
          example: GB of storage used in my application
          description: Internal description of the billable metric.
          nullable: true
        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
          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.
          nullable: true
        rounding_function:
          type: string
          enum:
            - ceil
            - floor
            - round
          nullable: true
          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
          example: 2
          nullable: true
          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
          example: gb
          description: Property of the billable metric used for aggregating usage data. This field is not required for `count_agg`.
          nullable: true
        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
          enum:
            - seconds
          nullable: true
          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
    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
    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
    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
    BillableMetricUpdateInput:
      type: object
      required:
        - billable_metric
      properties:
        billable_metric:
          $ref: '#/components/schemas/BillableMetricBaseInput'
    BillableMetricsPaginated:
      type: object
      required:
        - billable_metrics
        - meta
      properties:
        billable_metrics:
          type: array
          items:
            $ref: '#/components/schemas/BillableMetricObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    ChargeFilterInput:
      type: object
      description: Values used to apply differentiated pricing based on additional event properties.
      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 values of the filter will be used as the default display name.'
          example: AWS
          nullable: true
        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
    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
          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
          nullable: true
        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
      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
        billable_metric_code:
          type: string
          description: Unique code identifying a billable metric.
          example: requests
        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
        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:
          type: string
          description: 'Specifies the pricing model used for the calculation of the final fee. It can be `standard`, `graduated`, `graduated_percentage`, `package`, `percentage`, `volume` or `dynamic`.'
          enum:
            - standard
            - graduated
            - graduated_percentage
            - package
            - percentage
            - volume
            - dynamic
        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
          nullable: true
          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/ChargeProperties'
          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'
    ChargeProperties:
      type: object
      properties:
        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
                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.
                nullable: true
                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
                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.
                nullable: true
                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
          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.
          nullable: true
          example: 5
        free_units_per_total_aggregation:
          type: string
          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.
          nullable: true
          example: '500'
        per_transaction_max_amount:
          type: string
          format: '^[0-9]+.?[0-9]*$'
          description: Specifies the maximum allowable spending for a single transaction. Working as a transaction cap.
          nullable: true
          example: '3.75'
        per_transaction_min_amount:
          type: string
          format: '^[0-9]+.?[0-9]*$'
          description: Specifies the minimum allowable spending for a single transaction. Working as a transaction floor.
          nullable: true
          example: '1.75'
        grouped_by:
          type: array
          description: 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
        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
                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.
                nullable: true
                example: 10
              flat_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: '10'
              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. It is expressed as a decimal value.'
                example: '0.5'
    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
    Coupon:
      type: object
      required:
        - coupon
      properties:
        coupon:
          $ref: '#/components/schemas/CouponObject'
    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
          nullable: true
          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
          nullable: true
          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/Currency'
          description: The currency of the coupon. This field is required only for coupon with `fixed_amount` type.
          nullable: true
          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
          pattern: '^[0-9]+.?[0-9]*$'
          nullable: true
          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
          nullable: true
          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
          format: date-time
          nullable: true
          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
          description: Set coupon limitations to plans or specific metrics.
          nullable: true
          properties:
            plan_codes:
              type: array
              nullable: true
              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
              nullable: true
              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
    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
          nullable: true
          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
          nullable: true
          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/Currency'
          nullable: true
          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
          pattern: '^[0-9]+.?[0-9]*$'
          nullable: true
          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
          nullable: true
          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
          format: date-time
          nullable: true
          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
          format: date-time
          nullable: true
          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'
    CouponUpdateInput:
      type: object
      required:
        - coupon
      properties:
        coupon:
          $ref: '#/components/schemas/CouponBaseInput'
    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
            - sub_total_excluding_taxes_amount_cents
            - max_creditable_amount_cents
            - max_refundable_amount_cents
            - 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
            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
            coupons_adjustment_amount_cents:
              type: integer
              description: The pro-rated amount of the coupons applied to the source invoice.
              example: 20
            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
                    format: uuid
                    nullable: true
                    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
    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
    CreditNote:
      type: object
      required:
        - credit_note
      properties:
        credit_note:
          $ref: '#/components/schemas/CreditNoteObject'
    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
    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.
    CreditNoteObject:
      type: object
      required:
        - lago_id
        - sequential_id
        - number
        - lago_invoice_id
        - invoice_number
        - issuing_date
        - reason
        - currency
        - total_amount_cents
        - credit_amount_cents
        - refund_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
        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
          enum:
            - available
            - consumed
            - voided
          nullable: true
          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
          enum:
            - pending
            - succeeded
            - failed
          nullable: true
          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
          nullable: true
          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
        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
          nullable: true
          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'
    CreditNotes:
      type: object
      required:
        - credit_notes
      properties:
        credit_notes:
          type: array
          items:
            $ref: '#/components/schemas/CreditNoteObject'
    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
              enum:
                - duplicated_charge
                - product_unsatisfactory
                - order_change
                - order_cancellation
                - fraudulent_charge
                - other
              nullable: true
              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
              nullable: true
              description: The total amount to be credited on the customer balance.
              example: 10
            refund_amount_cents:
              type: integer
              nullable: true
              description: The total amount to be refunded to the customer.
              example: 5
            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
    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
    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
        - 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
    Customer:
      type: object
      required:
        - customer
      properties:
        customer:
          $ref: '#/components/schemas/CustomerObjectExtended'
    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
          example: 5230 Penfield Ave
          description: The first line of the billing address
          nullable: true
        address_line2:
          type: string
          example: null
          description: The second line of the billing address
          nullable: true
        city:
          type: string
          example: Woodland Hills
          description: The city of the customer's billing address
          nullable: true
        country:
          $ref: '#/components/schemas/Country'
          nullable: true
          description: Country code of the customer's billing address. Format must be ISO 3166 (alpha-2)
          example: US
        state:
          type: string
          example: CA
          description: The state of the customer's billing address
          nullable: true
        zipcode:
          type: string
          example: '91364'
          description: The zipcode of the customer's billing address
          nullable: true
    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'
        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
          nullable: true
          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` and `link`. Note that when `link` is selected, `card` should also be provided in the array.'
          example:
            - card
            - sepa_debit
    IntegrationCustomer:
      type: object
      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
        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.
    CustomerChargeFiltersUsageObject:
      type: array
      description: 'Array of filter object, representing multiple dimensions for a charge item.'
      required:
        - values
        - 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.
          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
          values:
            type: object
            description: List of filter values applied to the usage.
            additionalProperties:
              type: string
            example:
              region: us-east-1
    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
        - 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.
          grouped_by:
            type: object
            description: Key value list of event properties aggregated by the charge model
            additionalProperties:
              type: string
          filters:
            $ref: '#/components/schemas/CustomerChargeFiltersUsageObject'
    CustomerChargeUsageObject:
      type: object
      required:
        - units
        - events_count
        - 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.
        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
        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/CustomerChargeFiltersUsageObject'
        grouped_usage:
          $ref: '#/components/schemas/CustomerChargeGroupedUsageObject'
    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)
            address_line1:
              type: string
              example: 5230 Penfield Ave
              description: The first line of the billing address
              nullable: true
            address_line2:
              type: string
              example: ''
              description: The second line of the billing address
              nullable: true
            city:
              type: string
              example: Woodland Hills
              description: The city of the customer's billing address
              nullable: true
            country:
              $ref: '#/components/schemas/Country'
              nullable: true
              description: Country code of the customer's billing address. Format must be ISO 3166 (alpha-2)
              example: US
            currency:
              $ref: '#/components/schemas/Currency'
              description: Currency of the customer. Format must be ISO 4217
              nullable: true
            email:
              type: string
              format: email
              example: dinesh@piedpiper.test
              description: The email of the customer
              nullable: true
            legal_name:
              type: string
              example: Coleman-Blair
              description: The legal company name of the customer
              nullable: true
            legal_number:
              type: string
              example: 49-008-2965
              description: The legal company number of the customer
              nullable: true
            logo_url:
              type: string
              example: 'http://hooli.com/logo.png'
              description: The logo URL of the customer
              nullable: true
            name:
              type: string
              example: Gavin Belson
              description: The full name of the customer
              nullable: true
            firstname:
              type: string
              example: Gavin
              description: First name of the customer
              nullable: true
            lastname:
              type: string
              example: Belson
              description: Last name of the customer
              nullable: true
            customer_type:
              type: string
              enum:
                - company
                - individual
              nullable: true
              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
              example: 1-171-883-3711 x245
              description: The phone number of the customer
              nullable: true
            state:
              type: string
              example: CA
              description: The state of the customer's billing address
              nullable: true
            tax_codes:
              type: array
              items:
                type: string
              description: List of unique code used to identify the taxes.
              example:
                - french_standard_vat
            tax_identification_number:
              type: string
              example: EU123456789
              description: The tax identification number of the customer
              nullable: true
            timezone:
              $ref: '#/components/schemas/Timezone'
              description: 'The customer''s timezone, used for billing purposes in their local time. Overrides the organization''s timezone'
              nullable: true
            url:
              type: string
              example: 'http://hooli.com'
              description: The custom website URL of the customer
              nullable: true
            zipcode:
              type: string
              example: '91364'
              description: The zipcode of the customer's billing address
              nullable: 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.'
              nullable: true
            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.'
    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'
    CustomerObject:
      allOf:
        - 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)
            address_line1:
              type: string
              example: 5230 Penfield Ave
              description: The first line of the billing address
              nullable: true
            address_line2:
              type: string
              example: null
              description: The second line of the billing address
              nullable: true
            applicable_timezone:
              $ref: '#/components/schemas/Timezone'
              description: 'The customer''s applicable timezone, used for billing purposes in their local time.'
            city:
              type: string
              example: Woodland Hills
              description: The city of the customer's billing address
              nullable: true
            country:
              $ref: '#/components/schemas/Country'
              nullable: true
              description: Country code of the customer's billing address. Format must be ISO 3166 (alpha-2)
              example: US
            currency:
              $ref: '#/components/schemas/Currency'
              example: USD
              description: Currency of the customer. Format must be ISO 4217
              nullable: true
            email:
              type: string
              format: email
              example: dinesh@piedpiper.test
              description: The email of the customer
              nullable: true
            legal_name:
              type: string
              example: Coleman-Blair
              description: The legal company name of the customer
              nullable: true
            legal_number:
              type: string
              example: 49-008-2965
              description: The legal company number of the customer
              nullable: true
            logo_url:
              type: string
              example: 'http://hooli.com/logo.png'
              description: The logo URL of the customer
              nullable: true
            name:
              type: string
              example: Gavin Belson
              description: The full name of the customer
              nullable: true
            firstname:
              type: string
              example: Gavin
              description: First name of the customer
              nullable: true
            lastname:
              type: string
              example: Belson
              description: Last name of the customer
              nullable: true
            customer_type:
              type: string
              enum:
                - company
                - individual
              nullable: true
              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
              example: 1-171-883-3711 x245
              description: The phone number of the customer
              nullable: true
            state:
              type: string
              example: CA
              description: The state of the customer's billing address
              nullable: true
            tax_identification_number:
              type: string
              example: EU123456789
              description: The tax identification number of the customer
              nullable: true
            timezone:
              $ref: '#/components/schemas/Timezone'
              description: 'The customer''s timezone, used for billing purposes in their local time. Overrides the organization''s timezone'
              nullable: true
            url:
              type: string
              example: 'http://hooli.com'
              description: The custom website URL of the customer
              nullable: true
            zipcode:
              type: string
              example: '91364'
              description: The zipcode of the customer's billing address
              nullable: 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.'
              nullable: true
            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.
            billing_configuration:
              $ref: '#/components/schemas/CustomerBillingConfiguration'
            shipping_address:
              $ref: '#/components/schemas/Address'
            metadata:
              type: array
              items:
                $ref: '#/components/schemas/CustomerMetadata'
        - type: object
          properties:
            integration_customers:
              type: array
              items:
                $ref: '#/components/schemas/IntegrationCustomer'
    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'
    CustomerPastUsage:
      type: object
      required:
        - usage_periods
        - meta
      properties:
        usage_periods:
          type: array
          items:
            $ref: '#/components/schemas/CustomerUsage'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    CustomersPaginated:
      type: object
      required:
        - customers
        - meta
      properties:
        customers:
          type: array
          items:
            $ref: '#/components/schemas/CustomerObjectExtended'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    CustomerUsage:
      type: object
      required:
        - customer_usage
      properties:
        customer_usage:
          $ref: '#/components/schemas/CustomerUsageObject'
    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
          format: uuid
          nullable: true
          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'
    Event:
      type: object
      required:
        - event
      properties:
        event:
          $ref: '#/components/schemas/EventObject'
    EventBatchInput:
      type: object
      required:
        - events
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventInput/properties/event'
    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.'
    EventInput:
      type: object
      required:
        - event
      properties:
        event:
          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.'
            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:
              anyOf:
                - 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
              nullable: true
              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
              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
    EventObject:
      type: object
      required:
        - lago_id
        - transaction_id
        - lago_customer_id
        - code
        - timestamp
        - lago_subscription_id
        - external_subscription_id
        - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          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
        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
          format: uuid
          nullable: true
          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
          nullable: true
          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
              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
          format: uuid
          nullable: true
          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
          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'
    Fee:
      type: object
      required:
        - fee
      properties:
        fee:
          $ref: '#/components/schemas/FeeObject'
    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
    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
        - precise_unit_amount
        - payment_status
      properties:
        lago_id:
          type: string
          format: uuid
          nullable: true
          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
          format: uuid
          nullable: true
          description: Unique identifier assigned to the charge that the fee belongs to
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_charge_filter_id:
          type: string
          format: uuid
          nullable: true
          description: Unique identifier assigned to the charge filter that the fee belongs to
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        lago_invoice_id:
          type: string
          format: uuid
          nullable: true
          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
          format: uuid
          nullable: true
          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
          format: uuid
          nullable: true
          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
          format: uuid
          nullable: true
          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
          nullable: true
          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
          nullable: true
          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
          nullable: true
          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
        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)
        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_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: 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
          format: date-time
          nullable: true
          description: The beginning date of the period that the fee covers. It is applicable only to `subscription` and `charge` 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
          format: date-time
          nullable: true
          description: The ending date of the period that the fee covers. It is applicable only to `subscription` and `charge` 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
          format: date-time
          nullable: true
          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
          format: date-time
          nullable: true
          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
          format: date-time
          nullable: true
          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
          format: date-time
          nullable: true
          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
          nullable: true
          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:
          description: List of all unit amount details for calculating the fee.
          type: object
          properties:
            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
                    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.
                    nullable: true
                    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
                    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.
                    nullable: true
                    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'
            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'
            per_unit_total_amount:
              type: string
              description: Total amount of received units to be charged for the Percentage charge model.
              example: '10.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'
            volume_ranges:
              type: array
              description: 'Volume ranges, used for a `volume` charge model.'
              items:
                type: object
                required:
                  - per_unit_amount
                  - flat_unit_amount
                  - per_unit_total_amount
                properties:
                  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'
                  per_unit_total_amount:
                    type: string
                    pattern: '^[0-9]+.?[0-9]*$'
                    description: Total amount of received units to be charged.
                    example: '10.0'
        item:
          type: object
          description: Item attached to the fee
          required:
            - type
            - code
            - name
            - lago_item_id
            - item_type
          properties:
            type:
              type: string
              enum:
                - charge
                - add_on
                - subscription
                - credit
              description: 'The fee type. Possible values are `add-on`, `charge`, `credit` or `subscription`.'
              example: subscription
            code:
              type: string
              description: 'The code of the fee item. It can be the code of the `add-o`n, the code of the `charge`, the code of the `credit` or the code of the `subscription`.'
              example: startup
            name:
              type: string
              description: 'The name of the fee item. It can be the name of the `add-on`, the name of the `charge`, the name of the `credit` or the name of the `subscription`.'
              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 actual charge will be used as the default display name.'
              example: Setup Fee (SF1)
            filter_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 actual charge filter values will be used as the default display name.'
              example: AWS eu-east-1
            filters:
              type: object
              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 identifier of the `charge`, the identifier of the `credit` or the identifier of the `subscription`.'
              format: uuid
            item_type:
              type: string
              enum:
                - AddOn
                - BillableMetric
                - Subscription
                - WalletTransaction
              description: 'The type of the fee item. Possible values are `AddOn`, `BillableMetric`, `WalletTransaction` or `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'
    Fees:
      type: object
      required:
        - fees
      properties:
        fees:
          type: array
          items:
            $ref: '#/components/schemas/FeeObject'
    FeesPaginated:
      allOf:
        - $ref: '#/components/schemas/Fees'
        - type: object
          required:
            - meta
          properties:
            meta:
              $ref: '#/components/schemas/PaginationMeta'
    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
    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'
    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).
    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
          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'
    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
          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'
          nullable: true
    MinimumCommitmentInput:
      type: object
      description: Minimum commitment for this plan.
      nullable: true
      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:
          type: array
          items:
            type: string
          description: List of unique code used to identify the taxes.
          example:
            - french_standard_vat
    MinimumCommitmentObject:
      type: object
      nullable: true
      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`, `quarterly`, `monthly` or `weekly`.'
          enum:
            - weekly
            - monthly
            - quarterly
            - 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'
    MrrObject:
      type: object
      required:
        - month
      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'
    Invoice:
      type: object
      required:
        - invoice
      properties:
        invoice:
          $ref: '#/components/schemas/InvoiceObjectExtended'
    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
    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'
    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
          description: Represents the value of the metadata's key-value pair.
          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'
    InvoiceObject:
      allOf:
        - type: object
          required:
            - lago_id
            - 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
            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
              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.
              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
            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
            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'
            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'
        - 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_usage_thresholds:
              type: array
              nullable: true
              items:
                $ref: '#/components/schemas/AppliedUsageThresholdObject'
    InvoiceObjectExtended:
      allOf:
        - $ref: '#/components/schemas/InvoiceObject'
        - type: object
          properties:
            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:
                type: object
                required:
                  - lago_id
                  - error_code
                  - details
                properties:
                  lago_id:
                    type: string
                    format: uuid
                    nullable: true
                    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
    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
            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
                    nullable: true
                    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
                    pattern: '^[0-9]+.?[0-9]*$'
                    nullable: true
                    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
                    nullable: true
                    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
                  tax_codes:
                    type: array
                    items:
                      type: string
                    description: List of unique code used to identify the taxes.
                    example:
                      - french_standard_vat
    InvoicesPaginated:
      type: object
      required:
        - invoices
        - meta
      properties:
        invoices:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    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
                    description: The value in the key-value pair of the metadata.
                    example: INV-0123456-98765
    Organization:
      type: object
      required:
        - organization
      properties:
        organization:
          $ref: '#/components/schemas/OrganizationObject'
    OrganizationBillingConfiguration:
      type: object
      description: The custom billing settings for your organization.
      properties:
        invoice_footer:
          type: string
          example: This is my customer footer
          description: The customer invoice message that appears at the bottom of each billing documents.
          nullable: true
        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.'
    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
          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).'
          nullable: true
        webhook_url:
          type: string
          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.'
          nullable: true
        webhook_urls:
          type: array
          items:
            type: string
          example:
            - 'https://webhook.brex.com'
            - 'https://webhook2.brex.com'
          description: The array containing your webhooks URLs.
          nullable: true
        country:
          $ref: '#/components/schemas/Country'
          nullable: true
          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
          example: 100 Brex Street
          description: The first line of your organization's billing address.
          nullable: true
        address_line2:
          type: string
          example: null
          description: The second line of your organization's billing address.
          nullable: true
        state:
          type: string
          example: NYC
          description: The state of your organization's billing address.
          nullable: true
        zipcode:
          type: string
          example: '10000'
          description: The zipcode of your organization's billing address.
          nullable: true
        email:
          type: string
          format: email
          example: brex@brex.com
          description: The email address of your organization used to bill your customers.
          nullable: true
        city:
          type: string
          example: New York
          description: The city of your organization's billing address.
          nullable: true
        legal_name:
          type: string
          example: null
          description: The legal name of your organization.
          nullable: true
        legal_number:
          type: string
          example: null
          description: The legal number of your organization.
          nullable: true
        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
          example: US123456789
          description: The tax identification number of your organization.
          nullable: true
        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.'
    OrganizationUpdateInput:
      type: object
      required:
        - organization
      properties:
        organization:
          type: object
          properties:
            webhook_url:
              type: string
              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.'
              nullable: true
            country:
              $ref: '#/components/schemas/Country'
              nullable: true
              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
              example: 100 Brex Street
              description: The first line of your organization's billing address.
              nullable: true
            address_line2:
              type: string
              example: null
              description: The second line of your organization's billing address.
              nullable: true
            state:
              type: string
              example: NYC
              description: The state of your organization's billing address.
              nullable: true
            zipcode:
              type: string
              example: '10000'
              description: The zipcode of your organization's billing address.
              nullable: true
            email:
              type: string
              format: email
              example: brex@brex.com
              description: The email address of your organization used to bill your customers.
              nullable: true
            city:
              type: string
              example: New York
              description: The city of your organization's billing address.
              nullable: true
            legal_name:
              type: string
              example: null
              description: The legal name of your organization.
              nullable: true
            legal_number:
              type: string
              example: null
              description: The legal number of your organization.
              nullable: true
            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
              example: US123456789
              description: The tax identification number of your organization.
              nullable: true
            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.'
    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'
    PaginationMeta:
      type: object
      required:
        - current_page
        - total_pages
        - total_count
      properties:
        current_page:
          type: integer
          description: Current page.
          example: 2
        next_page:
          type: integer
          description: Next page.
          example: 3
          nullable: true
        prev_page:
          type: integer
          description: Previous page.
          example: 1
          nullable: true
        total_pages:
          type: integer
          description: Total number of pages.
          example: 4
        total_count:
          type: integer
          description: Total number of records.
          example: 70
    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/CustomerObject/allOf/0'
          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/InvoiceObject/allOf/0'
    PaymentRequestsPaginated:
      type: object
      required:
        - payment_requests
        - meta
      properties:
        payment_requests:
          type: array
          items:
            $ref: '#/components/schemas/PaymentRequestObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    Plan:
      type: object
      required:
        - plan
      properties:
        plan:
          $ref: '#/components/schemas/PlanObject'
    PlanCreateInput:
      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
              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`, `quarterly`, `monthly`, or `weekly`.'
              example: monthly
              enum:
                - weekly
                - monthly
                - quarterly
                - yearly
            description:
              type: string
              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
              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
              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. 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`.'
              nullable: true
              example: null
            tax_codes:
              type: array
              items:
                type: string
              description: List of unique code used to identify the taxes.
              example:
                - french_standard_vat
            minimum_commitment:
              $ref: '#/components/schemas/MinimumCommitmentInput'
            charges:
              type: array
              description: Additional usage-based charges for this plan.
              items:
                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
                  charge_model:
                    type: string
                    description: 'Specifies the pricing model used for the calculation of the final fee. It can be `standard`, `graduated`, `graduated_percentage` `package`, `percentage`, `volume` or `dynamic`.'
                    enum:
                      - standard
                      - graduated
                      - graduated_percentage
                      - package
                      - percentage
                      - volume
                      - dynamic
                    example: standard
                  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
                    nullable: true
                    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/ChargeProperties'
                    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:
                    type: array
                    items:
                      type: string
                    description: List of unique code used to identify the taxes.
                    example:
                      - french_standard_vat
              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'
            usage_thresholds:
              type: array
              description: List of usage thresholds to apply to the plan.
              items:
                $ref: '#/components/schemas/UsageThresholdInput'
    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:
          type: array
          items:
            type: string
          description: List of unique code used to identify the taxes.
          example:
            - french_standard_vat
        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/MinimumCommitmentObject'
        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
              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/ChargeProperties'
                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:
                type: array
                items:
                  type: string
                description: List of unique code used to identify the taxes.
                example:
                  - french_standard_vat
        usage_thresholds:
          type: array
          description: List of usage thresholds applied to the subscription.
          items:
            $ref: '#/components/schemas/UsageThresholdObject'
    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
              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`, `quarterly`, `monthly`, or `weekly`.'
              example: monthly
              enum:
                - weekly
                - monthly
                - quarterly
                - yearly
            description:
              type: string
              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
              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
              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. 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`.'
              nullable: true
              example: null
            tax_codes:
              type: array
              items:
                type: string
              description: List of unique code used to identify the taxes.
              example:
                - french_standard_vat
            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
                  charge_model:
                    type: string
                    description: 'Specifies the pricing model used for the calculation of the final fee. It can be `standard`, `graduated`, `graduated_percentage`, `package`, `percentage`, `volume` or `dynamic`.'
                    enum:
                      - standard
                      - graduated
                      - graduated_percentage
                      - package
                      - percentage
                      - volume
                      - dynamic
                    example: standard
                  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
                    nullable: true
                    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/ChargeProperties'
                    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:
                    type: array
                    items:
                      type: string
                    description: List of unique code used to identify the taxes.
                    example:
                      - french_standard_vat
              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'
            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
    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`, `quarterly`, `monthly` or `weekly`.'
          enum:
            - weekly
            - monthly
            - quarterly
            - 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
          nullable: true
          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. 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`.'
          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
              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
              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
              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: []
        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'
    PlansPaginated:
      type: object
      required:
        - plans
        - meta
      properties:
        plans:
          type: array
          items:
            $ref: '#/components/schemas/PlanObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    Subscription:
      type: object
      required:
        - subscription
      properties:
        subscription:
          $ref: '#/components/schemas/SubscriptionObjectExtended'
    SubscriptionCreateInput:
      type: object
      required:
        - subscription
      properties:
        subscription:
          type: object
          required:
            - external_customer_id
            - plan_code
            - external_id
          properties:
            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'
    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
              example: Repository B
              nullable: true
              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
              format: date-time
              example: '2022-10-08T00:00:00Z'
              nullable: true
              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'
    SubscriptionObject:
      type: object
      required:
        - lago_id
        - lago_customer_id
        - billing_time
        - external_customer_id
        - created_at
        - subscription_at
        - plan_code
        - external_id
        - status
      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_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
          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.'
          nullable: true
        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.
        status:
          type: string
          description: |-
            The status of the subscription, which can have the following values:
            - `pending`: a previous subscription has been downgraded, and the current one is awaiting automatic activation at the end of the billing period.
            - `active`: the subscription is currently active and applied to the customer.
            - `terminated`: the subscription is no longer active.
            - `canceled`: the subscription has been stopped before its activation. This can occur when two consecutive downgrades have been applied to a customer or when a subscription with a pending status is terminated.
          example: active
          enum:
            - active
            - pending
            - terminated
            - canceled
        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
          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).
          nullable: true
        started_at:
          type: string
          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).
          nullable: true
        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).'
          nullable: true
        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
          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)
          nullable: true
        previous_plan_code:
          type: string
          example: null
          description: The code identifying the previous plan associated with this subscription.
          nullable: true
        next_plan_code:
          type: string
          example: null
          description: The code identifying the next plan in the case of a downgrade.
          nullable: true
        downgrade_plan_date:
          type: string
          format: date
          example: '2022-04-30'
          description: 'The date when the plan will be downgraded, represented in ISO 8601 date format.'
          nullable: true
        trial_ended_at:
          type: string
          format: date-time
          example: '2022-08-08T00:00:00Z'
          description: 'The date when the free trial is ended, represented in ISO 8601 date format.'
          nullable: true
        current_billing_period_started_at:
          type: string
          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.'
          nullable: true
        current_billing_period_ending_at:
          type: string
          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.'
          nullable: true
    SubscriptionObjectExtended:
      allOf:
        - $ref: '#/components/schemas/SubscriptionObject'
        - type: object
          properties:
            plan:
              $ref: '#/components/schemas/PlanObject'
    SubscriptionsPaginated:
      type: object
      required:
        - subscriptions
        - meta
      properties:
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    Tax:
      type: object
      required:
        - tax
      properties:
        tax:
          $ref: '#/components/schemas/TaxObject'
    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
          nullable: true
          description: Internal description of the taxe
          example: French standard VAT
        applied_to_organization:
          type: boolean
          description: Set to `true` if the tax is used as one of the organization's default
          example: true
    TaxCreateInput:
      type: object
      required:
        - tax
      properties:
        tax:
          $ref: '#/components/schemas/TaxBaseInput'
          required:
            - name
            - code
            - rate
    TaxesPaginated:
      type: object
      required:
        - taxes
        - meta
      properties:
        taxes:
          type: array
          items:
            $ref: '#/components/schemas/TaxObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    TaxObject:
      type: object
      required:
        - lago_id
        - name
        - code
        - rate
        - applied_to_organization
        - customers_count
        - 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
          description: Internal description of the taxe
          example: French standard VAT
        rate:
          type: number
          description: The percentage rate of the tax
          example: 20
        applied_to_organization:
          type: boolean
          description: Set to `true` if the tax is used as one of the organization's default
          example: true
        created_at:
          type: string
          format: date-time
          description: Creation date of the tax.
          example: '2023-07-06T14:35:58Z'
    TaxUpdateInput:
      type: object
      required:
        - tax
      properties:
        tax:
          $ref: '#/components/schemas/TaxBaseInput'
    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/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
    UsageThresholdInput:
      type: object
      required:
        - amount_cents
        - recurring
      properties:
        id:
          type: string
          format: uuid
          nullable: true
          description: Unique identifier of the usage threshold created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        threshold_display_name:
          type: string
          nullable: true
          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
    UsageThresholdObject:
      type: object
      required:
        - lago_id
        - 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
          nullable: true
          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'
    Wallet:
      type: object
      required:
        - wallet
      properties:
        wallet:
          $ref: '#/components/schemas/WalletObject'
    WalletCreateInput:
      type: object
      properties:
        wallet:
          type: object
          required:
            - rate_amount
            - currency
            - external_customer_id
          properties:
            name:
              type: string
              description: The name of the wallet.
              example: Prepaid
            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
              pattern: '^[0-9]+.?[0-9]*$'
              nullable: true
              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]*$'
              nullable: true
              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
            expiration_at:
              type: string
              format: date-time
              nullable: true
              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
              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
            recurring_transaction_rules:
              type: array
              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
                    pattern: '^[0-9]+.?[0-9]*$'
                    nullable: true
                    description: The number of paid credits used for recurring top-up.
                    example: '20.0'
                  granted_credits:
                    type: string
                    pattern: '^[0-9]+.?[0-9]*$'
                    nullable: true
                    description: The number of free granted credits used for recurring top-up.
                    example: '10.0'
                  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
                      - 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` or `yearly`. Required only when trigger is `interval`.'
                    example: monthly
                  started_at:
                    type: string
                    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).
                  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
    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
        - 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
        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
          description: The name of the wallet.
          example: Prepaid
        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
          format: date-time
          nullable: true
          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
          format: date-time
          nullable: true
          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
          format: date-time
          nullable: true
          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
          format: date-time
          nullable: true
          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
        recurring_transaction_rules:
          description: 'List of recurring transaction rules. Currently, we only allow one recurring rule per wallet.'
          type: array
          items:
            type: object
            description: Object that represents rule for wallet recurring transactions.
            required:
              - lago_id
              - interval
              - trigger
              - method
              - paid_credits
              - granted_credits
              - threshold_credits
              - target_ongoing_balance
              - created_at
            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
                  - 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` or `yearly`. Required only if 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
                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'
              started_at:
                type: string
                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
                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'
              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
        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'
    WalletsPaginated:
      type: object
      required:
        - wallets
        - meta
      properties:
        wallets:
          type: array
          items:
            $ref: '#/components/schemas/WalletObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    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
            paid_credits:
              type: string
              pattern: '^[0-9]+.?[0-9]*$'
              description: The number of paid credits.
              example: '20.0'
            granted_credits:
              type: string
              pattern: '^[0-9]+.?[0-9]*$'
              description: The number of free granted credits.
              example: '10.0'
            voided_credits:
              type: string
              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
            metadata:
              type: array
              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
        - status
        - transaction_status
        - transaction_type
        - credit_amount
        - amount
        - created_at
      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
        status:
          type: string
          enum:
            - pending
            - settled
          description: The status of the wallet transaction. Possible values are `pending` or `settled`.
          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
        settled_at:
          type: string
          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'
        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'
    WalletTransactions:
      type: object
      required:
        - wallet_transactions
      properties:
        wallet_transactions:
          type: array
          items:
            $ref: '#/components/schemas/WalletTransactionObject'
    WalletTransactionsPaginated:
      allOf:
        - $ref: '#/components/schemas/WalletTransactions'
        - type: object
          required:
            - meta
          properties:
            meta:
              $ref: '#/components/schemas/PaginationMeta'
    WalletUpdateInput:
      type: object
      required:
        - wallet
      properties:
        wallet:
          type: object
          properties:
            name:
              type: string
              nullable: true
              description: The name of the wallet.
              example: new_name
            expiration_at:
              type: string
              format: date-time
              nullable: true
              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
            recurring_transaction_rules:
              type: array
              description: 'List of recurring transaction rules. Currently, we only allow one recurring rule per wallet.'
              required:
                - trigger
                - paid_credits
                - granted_credits
              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
                      - 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` 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
                    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'
                  started_at:
                    type: string
                    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
                    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
    WebhookEndpoint:
      type: object
      required:
        - webhook_endpoint
      properties:
        webhook_endpoint:
          $ref: '#/components/schemas/WebhookEndpointObject'
    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
              description: 'The signature used for the webhook. If no value is passed,'
              example: hmac
              nullable: true
              enum:
                - jwt
                - hmac
    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 name of the wallet.
          example: Prepaid
        signature_algo:
          type: string
          description: The signature algo for the webhook.
          example: hmac
          enum:
            - jwt
            - hmac
        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'
    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
              description: 'The signature used for the webhook. If no value is passed,'
              example: hmac
              nullable: true
              enum:
                - jwt
                - hmac
  responses:
    BadRequest:
      description: Bad Request error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorBadRequest'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorForbidden'
    Unauthorized:
      description: Unauthorized error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorUnauthorized'
    NotAllowed:
      description: Not Allowed error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorNotAllowed'
    NotFound:
      description: Not Found error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorNotFound'
    UnprocessableEntity:
      description: Unprocessable entity error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorUnprocessableEntity'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer