openapi: 3.1.1
info:
  title: Invoice
  version: 2.2.0
  description: Schema definition for Invoice in the Beckn Protocol v2.0.1
  license:
    name: CC-BY-NC-SA 4.0 International
  contact:
    name: Beckn Labs
    url: https://beckn.io
components:
  schemas:
    Invoice:
      x-iri: https://schema.nfh.global/Invoice/v2.2
      description: An Invoice is a financial statement issued by a creditor to a debtor
        that itemises the amounts owed and records how they are settled. Each line item
        is a billed financial entry — an order, refund, commission, finder fee, or
        adjustment — rather than a product or service. The invoice tracks its lifecycle
        status, the agreed settlement terms, and the proofs of settlement (payment
        actions) that discharge the amount due. An invoice may be issued, updated,
        settled, cancelled, or disputed over its lifecycle.
      title: Invoice
      type: object
      properties:
        id:
          description: Stable invoice identifier (system id). While the chances of a
            UUID collision are rare, a combination of issuer identity and this id is
            recommended for global uniqueness.
          type: string
          format: uuid
        number:
          description: Human-visible invoice number.
          type: string
        issuedAt:
          description: Timestamp at which the invoice was issued.
          type: string
          format: date-time
        dueDate:
          description: Date by which the invoice amount is due for settlement.
          type: string
          format: date
        descriptor:
          description: Describes the nature of the invoice in human / agent readable
            terms.
          $ref: https://schema.nfh.global/Descriptor/v2.1/attributes.yaml#/components/schemas/Descriptor
        status:
          description: The lifecycle state of the invoice expressed as a Descriptor
            whose code MUST be one of the standard invoice state values.
          allOf:
          - $ref: https://schema.nfh.global/Descriptor/v2.1/attributes.yaml#/components/schemas/Descriptor
          - type: object
            properties:
              code:
                enum:
                - DRAFT
                - PENDING
                - COMMITTED
                - SETTLED
                - CANCELLED
                - DISPUTED
                default: PENDING
        creditor:
          description: The party that is owed the net amount — the seller / provider.
          $ref: https://schema.nfh.global/Participant/v2.0/attributes.yaml#/components/schemas/Participant
        debtor:
          description: The party the invoice is issued to and who owes the net amount — the consumer being billed.
          $ref: https://schema.nfh.global/Participant/v2.0/attributes.yaml#/components/schemas/Participant
        statement:
          description: The itemised statement of charges that make up the invoice.
            Each entry pairs a consideration — the value being billed, whose
            considerationAttributes carries a JSON-LD object (by @type) identifying
            the underlying item such as a Contract, RetailOrder, DeliveryService,
            Commission, FinderFee, Adjustment, or Refund — with the monetary amount for that entry.
          type: array
          minItems: 1
          items:
            type: object
            properties:
              consideration:
                description: The value being billed by this entry. Its
                  considerationAttributes carries the JSON-LD object (@type) identifying
                  what is billed — e.g. a Contract, RetailOrder, DeliveryService,
                  Commission, FinderFee, Adjustment, or Refund.
                allOf:
                - $ref: https://schema.nfh.global/Consideration/v2.0/attributes.yaml#/components/schemas/Consideration
                - type: object
                  properties:
                    status:
                      description: The lifecycle state of this billed entry, set and
                        updated by the creditor or debtor as it moves from raised
                        through to settled. The code MUST be one of the standard values.
                      properties:
                        code:
                          enum:
                          - PENDING
                          - COMMITTED
                          - DISPUTED
                          - SETTLED
                          default: PENDING
              amount:
                description: The monetary amount for this statement entry.
                $ref: https://schema.nfh.global/PriceSpecification/v2.1/attributes.yaml#/components/schemas/PriceSpecification
            required:
            - consideration
            - amount
            additionalProperties: false
        total:
          description: The net amount payable for this invoice across all line items.
          $ref: https://schema.nfh.global/PriceSpecification/v2.1/attributes.yaml#/components/schemas/PriceSpecification
        settlementTerms:
          description: The agreed terms under which the invoice is to be settled —
            amount, payment trigger, schedule, remittance account, and accepted methods.
          $ref: https://schema.nfh.global/SettlementTerm/v2.0/attributes.yaml#/components/schemas/SettlementTerm
        settlementAction:
          description: Proofs of settlement that discharge the invoice — one entry per
            payment event (supporting installments and partial payments), carrying the
            transaction reference, method, time, amount, and status.
          type: array
          items:
            $ref: https://schema.nfh.global/PaymentAction/v2.0/attributes.yaml#/components/schemas/PaymentAction
        invoiceAttributes:
          description: Domain-specific extension attributes for this invoice — tax
            regime (e.g. GST/VAT), e-invoice refs, legal boilerplate, etc.
          $ref: https://schema.nfh.global/Attributes/v2.0/attributes.yaml#/components/schemas/Attributes
      additionalProperties: false
      required:
      - id
      - number
      - issuedAt
      - creditor
      - debtor
      - statement
      x-tags:
      - common