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

# Compute finance mappings

Use a finance mapping when you need to represent a customer payable or a supported provider
reconciliation in a registered accounting system. First identify the commercial flow and external
object you need to reconcile; then select the registered system family and its exact recipe.

## Registered system families

The current finance authority recognizes these customer accounting-system families:

<!-- COMPUTE_FINANCE_RECIPES:START -->
| Raw recipe identifier | Payable object | Edition required |
| --- | --- | --- |
| `quickbooks-online` | `Bill` | `false` |
| `xero` | `ACCPAY` | `false` |
| `sage-intacct` | `APBILL` | `false` |
| `oracle-netsuite` | `vendorBill` | `true` |
| `microsoft-dynamics-365` | `purchaseInvoices` | `true` |
| `sap-s4hana` | `Supplier Invoice` | `true` |
| `other` | `registered_finance_adapter` | `true` |
<!-- COMPUTE_FINANCE_RECIPES:END -->

The current finance mapping authority supplies the exact system edition, external object kind, schema, and field mapping. Do not infer a mapping from the vendor name alone.

## Read a mapping record

Use the recipe identifiers above to select a system recipe. The `system_family` values below belong to the mapping record and use their own exact spelling; do not convert one into the other by replacing punctuation.

Each mapping carries these required fields:

<!-- COMPUTE_FINANCE_MAPPING_FIELDS:START -->
| Required mapping field | Contract constraint |
| --- | --- |
| `commercial_flow` | `customer_payable`, `provider_receivable`, `provider_payout_reconciliation` |
| `system_family` | `quickbooks_online`, `xero`, `sage_intacct`, `oracle_netsuite`, `microsoft_dynamics_365`, `sap_s4hana`, `registered_finance_adapter`, `none_export_only` |
| `system_edition` | `not_applicable`, `quickbooks_online_standard`, `xero_business`, `sage_intacct_standard`, `oracle_netsuite_standard`, `dynamics_365_business_central`, `dynamics_365_finance`, `sap_s4hana_cloud`, `sap_s4hana_on_premise`, `registered_adapter_edition` |
| `external_object_kind` | `quickbooks_bill`, `xero_accpay`, `sage_apbill`, `netsuite_vendor_bill`, `dynamics_business_central_purchase_invoice`, `sap_supplier_invoice`, `sales_invoice`, `self_billing_statement`, `income_receipt`, `payout_reconciliation`, `export_only` |
| `accounting_treatment` | `customer_payable_bill`, `provider_issued_sales_invoice`, `lithi_self_billing_statement`, `other_income_receipt`, `payout_reconciliation_only`, `export_only` |
| `recipe_version` | pattern `^v[1-9][0-9]{0,7}$` |
| `recipe_digest` | pattern `^[a-f0-9]{64}$` |
| `safe_external_reference` | pattern `^[A-Za-z0-9:._-]{1,256}$` |
| `mapping_digest` | pattern `^[a-f0-9]{64}$` |
<!-- COMPUTE_FINANCE_MAPPING_FIELDS:END -->

The shared contract includes customer and provider records. Customer invoice mappings use `commercial_flow: customer_payable`, with `accounting_treatment` set to `customer_payable_bill` or `export_only`. The listed enum values do not make every combination valid; use the selected system's edition and object constraints.

Keep the recipe version and digest with the mapping digest when reconciling a record. A changed mapping must not silently replace the identity used for an earlier export. `safe_external_reference` is an external record reference, never a credential or invoice content.

## Mapping is not posting authority

The public finance mapping endpoint acknowledges a separately authorized mapping version:

~~~text title="Finance mapping endpoint and scope" kind="rules"
POST /v1/finance-mappings
scope: finance:write
~~~

The mapping operation does **not** authorize hosted ERP posting, payment, changing the invoice amount, changing a beneficiary, provider payout mutation, or widening account access.

A read-only finance credential cannot grant itself `finance:write`.

## Dry-run first

Use [Finance Sync](/docs/compute/billing/finance-sync) for the complete human workflow, including
the separate supported-apply and export-only paths. If apply is unavailable for the selected
connection, export the reviewed projection and complete the external accounting action in the
customer-owned system.

## Keep payment independent

Mapping an invoice to an external accounting object does not pay it. An external **Paid** annotation is not Lithi payment truth until permitted payment evidence is reconciled to the Lithi invoice.

Use [Invoices and payment](/docs/compute/billing/invoices-and-payment) for the payment journey.