Allocations

Allocations are the links between finance documents. They answer: what paid what, or what credited what.

Why they matter

Without allocations you only see isolated documents. With them you see:

• Whether an invoice is still outstanding
• Whether a receipt is fully used or has spare balance
• Whether an invoice has been credited in full or in part

Auto-allocation

Lavanda automatically allocates in most cases when documents are issued — you do not normally see a separate manual step. Auto-allocation runs as part of moving a document to the Issued state.

How it behaves:

• When a receipt or invoice is issued, the system looks for open documents on the same booking that can be matched.
• It applies oldest receipt to oldest open charge first (by issue date), settling each side until one has no remaining balance.
• Matching respects document type. Deposit and downpayment receipts only match their corresponding downpayment invoices; any leftover receipt balance then lands against ordinary charges. Credit, corrective, refund, refund reversal and payment reversal documents follow their own type-specific rules. A refund reversal note is always allocated in full to the refund note it reverses, and that allocation can’t be changed or removed.

Because auto-allocation runs on issue, an invoice’s or receipt’s allocations can change as a direct result of a webhook you receive. Your integration should refresh allocations after every webhook that touches invoices or receipts — not only when you expect a manual allocation.

Reading allocations from the AR API

Allocations are exposed on the external accounting API as a read model. There are two entry points:

1. The allocations field on any document — the links already made, each an amount moving from one document to another:

query DocumentAllocations($id: ID!) {
  accounting {
    documents(filters: { workspaceId: { eq: "workspace-id" }, id: { in: [$id] } }) {
      edges {
        node {
          id
          balance { amount currency }   # outstanding balance after allocations
          allocations {
            edges {
              node {
                allocatedAt
                amount { amount currency }
                fromDocument { id }
                toDocument { id }
              }
            }
          }
        }
      }
    }
  }
}

2. The allocatableDocuments query — the open documents on a booking that a given document could still be matched against (useful to preview or reconcile what auto-allocation will do):

query Allocatable($filters: AccountingAllocatableDocumentFilters!) {
  accounting {
    allocatableDocuments(filters: $filters) {
      edges { node { id balance { amount currency } } }
    }
  }
}

Manual allocation is not yet exposed on the external API. Allocations you retrieve are created by Lavanda’s auto-allocation engine. If you need to allocate or unallocate documents yourself, talk to your Lavanda representative — it is on the roadmap, not currently available externally.

Common links

• Receipt to invoice — Payment settles all or part of a charge.
• Credit note to invoice — Credit reduces all or part of a charge (including credit against a charge note where used).
• Refund note to receipt — Money returned against the payment it refunds.
• Refund reversal note to refund note — Cancels a refund that never reached the guest. When this link is made, the refund note’s link to the receipt is removed, so the receipt has open balance again.

Other links may appear for corrections and internal matching; treat each allocation as an amount moving between two documents.

Partial vs full

• Partial — Only part of the invoice is settled; balance remains.
• Full — Invoice balance is zero for that currency (paid, credited, or both).

Outstanding balance

Use the invoice balance together with its allocations:

• Balance zero — nothing left to collect on that invoice.
• Balance positive — still owed.

Credited without a single flag

Lavanda does not expose a simple credited yes/no switch. Instead:

• Credit notes allocated to the invoice, and/or
• Balance and credited details on the invoice

Your integration should derive credited state from those signals.

Practical sync tip

When any allocation changes, refresh both documents in the link (invoice and receipt or credit note) so your ERP stays consistent. When a refund reversal note is issued, refresh the refund reversal note, the refund note it reverses and the original receipt.