> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tilta.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mark an invoice as paid

> Signal that a buyer has repaid an invoice directly to the merchant outside of Tilta's collection process. Updates invoice status to PAID.

In some scenarios, a buyer may remit payment directly to the merchant rather than through Tilta's standard collection flow – for example, via bank transfer or legacy payment channel. When this happens, you must notify Tilta by marking the invoice as paid so that the buyer's credit facility is correctly updated and the invoice status reflects the settled state. This endpoint records the repayment event and closes out the financing obligation on Tilta's side.

<Warning>
  Only call this endpoint for out-of-band payments made directly to the merchant. Payments routed through Tilta's collection
  process (e.g., via Tilta's bank transfer reference) are recorded automatically – calling this endpoint for those payments may
  result in duplicate payment recording.
</Warning>

<Note>
  Marking an invoice as paid releases the financed amount back to the buyer's credit facility, restoring their available limit
  for future orders.
</Note>


## OpenAPI

````yaml POST /v1/invoices/{external_id}/paid
openapi: 3.0.0
info:
  version: 0.0.1
  title: Tilta API
  description: Tilta API documentation
servers:
  - url: https://api.tilta.io
    description: Tilta Production API
  - url: https://api.tilta-sandbox.io
    description: Tilta Sandbox API
security: []
paths:
  /v1/invoices/{external_id}/paid:
    post:
      tags:
        - Invoices
      summary: Mark an invoice as paid
      description: Marks the invoice as paid to the merchant (repaid).
      parameters:
        - schema:
            type: string
            maxLength: 100
            pattern: ^[a-zA-Z0-9-_]+$
            description: Unique identifier of an invoice.
          required: true
          name: external_id
          in: path
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  paid_at:
                    type: number
                    description: >-
                      Unix timestamp in seconds for the banking update recorded
                      for this invoice.
                    example: 1712419200
                required:
                  - paid_at
                description: >-
                  The invoice was marked as paid; `paid_at` reflects that
                  payment.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestSchema'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorizedRequestSchema'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/invoiceNotFoundSchema'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/markInvoicePaidConflictSchema'
      security:
        - bearerAuth: []
components:
  schemas:
    badRequestSchema:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: BAD_REQUEST
        error:
          type: string
          description: Error message for debugging purposes
          example: Request validation failed. 1 issue found.
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: Issue code
                example: INVALID_TYPE
              path:
                type: string
                description: Issue path starting with body, params, querystring, or headers
                example: body.registered_at
              message:
                type: string
                description: Issue message for debugging purposes
                example: Invalid type
            required:
              - code
              - path
              - message
          description: List of issues
          example:
            - code: INVALID_TYPE
              path: body.registered_at
              message: Invalid type
      required:
        - code
        - error
        - issues
      description: Bad Request, see error message for details.
      example:
        code: BAD_REQUEST
        error: Request validation failed. 1 issue found.
        issues:
          - code: INVALID_TYPE
            path: body.registered_at
            message: Invalid type
    unauthorizedRequestSchema:
      type: object
      properties:
        error:
          type: string
          description: Error details.
          example: Unauthorized
        code:
          type: string
          description: Error code.
          example: UNAUTHORIZED
      required:
        - error
        - code
      description: Unauthorized Request.
      example:
        error: Unauthorized
        code: UNAUTHORIZED
    invoiceNotFoundSchema:
      type: object
      properties:
        error:
          type: string
          description: Error details.
          example: No Entity found
        code:
          type: string
          description: Error code.
          example: NOT_FOUND
      required:
        - error
        - code
      description: No invoice found.
      example:
        error: No Entity found
        code: NOT_FOUND
    markInvoicePaidConflictSchema:
      type: object
      properties:
        error:
          type: string
          description: Error details.
          example: Invoice is already marked as paid.
        code:
          type: string
          description: Error code.
          example: CONFLICT
      required:
        - error
        - code
      description: Invoice is already marked as paid.
      example:
        error: Invoice is already marked as paid.
        code: CONFLICT
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your Tilta API key, sent as `Bearer <key>`.

````