# 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:

```graphql
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):

```graphql
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.