Lago API documentation — Invoices

naftiko: 1.0.0-alpha2
info:
  label: Lago API documentation — Invoices
  description: 'Lago API documentation — Invoices. 12 operations. Lead operation: Lago Create a one-off invoice. Self-contained
    Naftiko capability covering one Lago business surface.'
  tags:
  - Lago
  - Invoices
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    LAGO_API_KEY: LAGO_API_KEY
capability:
  consumes:
  - type: http
    namespace: lago-invoices
    baseUri: https://api.getlago.com/api/v1
    description: Lago API documentation — Invoices business capability. Self-contained, no shared references.
    resources:
    - name: invoices
      path: /invoices
      operations:
      - name: createinvoice
        method: POST
        description: Lago Create a one-off invoice
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: findallinvoices
        method: GET
        description: Lago List all invoices
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: issuing_date_from
          in: query
          type: string
          description: Filter invoices starting from a specific date.
        - name: issuing_date_to
          in: query
          type: string
          description: Filter invoices up to a specific date.
        - name: status
          in: query
          type: string
          description: Filter invoices by status. Possible values are `draft` or `finalized`.
        - name: payment_status
          in: query
          type: string
          description: Filter invoices by payment status. Possible values are `pending`, `failed` or `succeeded`.
        - name: payment_overdue
          in: query
          type: boolean
          description: Filter invoices by payment_overdue. Possible values are `true` or `false`.
        - name: search_term
          in: query
          type: string
          description: Search invoices by id, number, customer name, customer external_id or customer email.
        - name: currency
          in: query
          type: string
          description: Filter invoices by currency in. Possible values ISO 4217 currency codes.
        - name: payment_dispute_lost
          in: query
          type: boolean
          description: Filter invoices with a payment dispute lost. Possible values are `true` or `false`.
        - name: invoice_type
          in: query
          type: string
          description: Filter invoices by invoice type. Possible values are `subscription`, `add_on`, `credit`, `one_off`
            or `advance_charges`
    - name: invoices-lago_id
      path: /invoices/{lago_id}
      operations:
      - name: updateinvoice
        method: PUT
        description: Lago Update an invoice
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: findinvoice
        method: GET
        description: Lago Retrieve an invoice
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: invoices-lago_id-download
      path: /invoices/{lago_id}/download
      operations:
      - name: downloadinvoice
        method: POST
        description: Lago Download an invoice PDF
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: invoices-lago_id-finalize
      path: /invoices/{lago_id}/finalize
      operations:
      - name: finalizeinvoice
        method: PUT
        description: Lago Finalize a draft invoice
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: invoices-lago_id-lose_dispute
      path: /invoices/{lago_id}/lose_dispute
      operations:
      - name: losedisputeinvoice
        method: POST
        description: Lago Mark an invoice payment dispute as lost
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: invoices-lago_id-payment_url
      path: /invoices/{lago_id}/payment_url
      operations:
      - name: invoicepaymenturl
        method: POST
        description: Lago Generate a payment URL
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: invoices-lago_id-refresh
      path: /invoices/{lago_id}/refresh
      operations:
      - name: refreshinvoice
        method: PUT
        description: Lago Refresh a draft invoice
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: invoices-lago_id-retry
      path: /invoices/{lago_id}/retry
      operations:
      - name: retryinvoice
        method: POST
        description: Lago Retry generation of a failed invoice
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: invoices-lago_id-retry_payment
      path: /invoices/{lago_id}/retry_payment
      operations:
      - name: retrypayment
        method: POST
        description: Lago Retry an invoice payment
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: invoices-lago_id-void
      path: /invoices/{lago_id}/void
      operations:
      - name: voidinvoice
        method: POST
        description: Lago Void an invoice
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    authentication:
      type: bearer
      token: '{{env.LAGO_API_KEY}}'
  exposes:
  - type: rest
    namespace: lago-invoices-rest
    port: 8080
    description: REST adapter for Lago API documentation — Invoices. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/invoices
      name: invoices
      description: REST surface for invoices.
      operations:
      - method: POST
        name: createinvoice
        description: Lago Create a one-off invoice
        call: lago-invoices.createinvoice
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: findallinvoices
        description: Lago List all invoices
        call: lago-invoices.findallinvoices
        with:
          issuing_date_from: rest.issuing_date_from
          issuing_date_to: rest.issuing_date_to
          status: rest.status
          payment_status: rest.payment_status
          payment_overdue: rest.payment_overdue
          search_term: rest.search_term
          currency: rest.currency
          payment_dispute_lost: rest.payment_dispute_lost
          invoice_type: rest.invoice_type
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/invoices/{lago-id}
      name: invoices-lago-id
      description: REST surface for invoices-lago_id.
      operations:
      - method: PUT
        name: updateinvoice
        description: Lago Update an invoice
        call: lago-invoices.updateinvoice
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: findinvoice
        description: Lago Retrieve an invoice
        call: lago-invoices.findinvoice
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/invoices/{lago-id}/download
      name: invoices-lago-id-download
      description: REST surface for invoices-lago_id-download.
      operations:
      - method: POST
        name: downloadinvoice
        description: Lago Download an invoice PDF
        call: lago-invoices.downloadinvoice
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/invoices/{lago-id}/finalize
      name: invoices-lago-id-finalize
      description: REST surface for invoices-lago_id-finalize.
      operations:
      - method: PUT
        name: finalizeinvoice
        description: Lago Finalize a draft invoice
        call: lago-invoices.finalizeinvoice
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/invoices/{lago-id}/lose-dispute
      name: invoices-lago-id-lose-dispute
      description: REST surface for invoices-lago_id-lose_dispute.
      operations:
      - method: POST
        name: losedisputeinvoice
        description: Lago Mark an invoice payment dispute as lost
        call: lago-invoices.losedisputeinvoice
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/invoices/{lago-id}/payment-url
      name: invoices-lago-id-payment-url
      description: REST surface for invoices-lago_id-payment_url.
      operations:
      - method: POST
        name: invoicepaymenturl
        description: Lago Generate a payment URL
        call: lago-invoices.invoicepaymenturl
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/invoices/{lago-id}/refresh
      name: invoices-lago-id-refresh
      description: REST surface for invoices-lago_id-refresh.
      operations:
      - method: PUT
        name: refreshinvoice
        description: Lago Refresh a draft invoice
        call: lago-invoices.refreshinvoice
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/invoices/{lago-id}/retry
      name: invoices-lago-id-retry
      description: REST surface for invoices-lago_id-retry.
      operations:
      - method: POST
        name: retryinvoice
        description: Lago Retry generation of a failed invoice
        call: lago-invoices.retryinvoice
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/invoices/{lago-id}/retry-payment
      name: invoices-lago-id-retry-payment
      description: REST surface for invoices-lago_id-retry_payment.
      operations:
      - method: POST
        name: retrypayment
        description: Lago Retry an invoice payment
        call: lago-invoices.retrypayment
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/invoices/{lago-id}/void
      name: invoices-lago-id-void
      description: REST surface for invoices-lago_id-void.
      operations:
      - method: POST
        name: voidinvoice
        description: Lago Void an invoice
        call: lago-invoices.voidinvoice
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: lago-invoices-mcp
    port: 9090
    transport: http
    description: MCP adapter for Lago API documentation — Invoices. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: lago-create-one-off-invoice
      description: Lago Create a one-off invoice
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: lago-invoices.createinvoice
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: lago-list-all-invoices
      description: Lago List all invoices
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: lago-invoices.findallinvoices
      with:
        issuing_date_from: tools.issuing_date_from
        issuing_date_to: tools.issuing_date_to
        status: tools.status
        payment_status: tools.payment_status
        payment_overdue: tools.payment_overdue
        search_term: tools.search_term
        currency: tools.currency
        payment_dispute_lost: tools.payment_dispute_lost
        invoice_type: tools.invoice_type
      outputParameters:
      - type: object
        mapping: $.
    - name: lago-update-invoice
      description: Lago Update an invoice
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: lago-invoices.updateinvoice
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: lago-retrieve-invoice
      description: Lago Retrieve an invoice
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: lago-invoices.findinvoice
      outputParameters:
      - type: object
        mapping: $.
    - name: lago-download-invoice-pdf
      description: Lago Download an invoice PDF
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: lago-invoices.downloadinvoice
      outputParameters:
      - type: object
        mapping: $.
    - name: lago-finalize-draft-invoice
      description: Lago Finalize a draft invoice
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: lago-invoices.finalizeinvoice
      outputParameters:
      - type: object
        mapping: $.
    - name: lago-mark-invoice-payment-dispute
      description: Lago Mark an invoice payment dispute as lost
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: lago-invoices.losedisputeinvoice
      outputParameters:
      - type: object
        mapping: $.
    - name: lago-generate-payment-url
      description: Lago Generate a payment URL
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: lago-invoices.invoicepaymenturl
      outputParameters:
      - type: object
        mapping: $.
    - name: lago-refresh-draft-invoice
      description: Lago Refresh a draft invoice
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: lago-invoices.refreshinvoice
      outputParameters:
      - type: object
        mapping: $.
    - name: lago-retry-generation-failed-invoice
      description: Lago Retry generation of a failed invoice
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: lago-invoices.retryinvoice
      outputParameters:
      - type: object
        mapping: $.
    - name: lago-retry-invoice-payment
      description: Lago Retry an invoice payment
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: lago-invoices.retrypayment
      outputParameters:
      - type: object
        mapping: $.
    - name: lago-void-invoice
      description: Lago Void an invoice
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: lago-invoices.voidinvoice
      outputParameters:
      - type: object
        mapping: $.