Payment corrections

Payment-correction writes are enabled in internal beta with the matching Services release and ledger privileges. Production and the partner sandbox remain disabled pending their separate rollout. Existing read grants do not authorize writes.

Use the accounting summary and payment report together. The summary supplies sales, VAT, refunds, tips, gift-card deferral, and reconciliation. Its payment methods are raw. A ready payment report supplies the corrected allocation of those same sales between methods. It does not create additional sales or VAT.

Reports and access

Use the accounting summary together with the payment report. MCP connections use get_accounting_summary and get_payment_report with the same reporting rules. See Fiest MCP for connection setup.

Owners, admins, managers, and accountants with the required read permissions can read the financial report. Accountants receive financial figures and source evidence, while internal reasons, actor labels, and transfer notes are redacted. Only owners, admins, and managers can create or undo corrections. Management checks the current organization membership and restaurant access. Partner API and MCP connections also need the separately approved fiest.accounting.corrections.write scope and financial feature access. An accounting read grant alone cannot change a payment.

Partner API report reads and restaurant discovery require a restaurant owner/admin or an authorized Management organization owner/admin. A restaurant manager's correction grant permits only the correction workspace, preview, apply, and undo routes. Its required read scopes do not unlock other Partner API operations.

Read and reconcile

1. Discover the authorized restaurant and legal entity. Partner OAuth reads require fiest.restaurant.read and fiest.accounting.read; MCP reads require fiest.restaurant.read and fiest.analytics.read. Current membership, role, and feature permissions are checked on every request.
2. Read GET /v1/restaurants/:restaurantId/accounting-summary and GET /v1/restaurants/:restaurantId/payment-report, or call MCP get_accounting_summary and get_payment_report. Use identical restaurant, inclusive business dates, currency, timezone, and business-day cutoff. Use day scope for one date and month scope within a single calendar month; split longer imports into non-overlapping periods of at most 31 business dates.
3. Require balanced accounting reconciliation, complete tender attribution, zero reconciliation differences, known VAT rates, and payment status: ready. Ready requires complete day coverage, known per-rate gross/VAT evidence, and conservation of gross, net, VAT, and payment transaction counts. Missing ledger access, stale corrections, unknown VAT, or unproven source allocation requires review; never turn a null adjusted value into zero or silently use raw methods as corrected methods.
4. Compare the payment report's raw method amounts/counts and per-rate totals against the accounting summary. These are separate reads, so a sale or refund between calls can change the snapshot. Refetch both on a mismatch; do not book an allocation that cannot reconcile.
5. For an initial import, use the ready adjusted methods in place of raw methods. Keep sales, refund, VAT, tip, and deferral semantics from the accounting summary. Map tender accounts using the bookkeeper's chart of accounts. These reads do not prove bank settlement, provider fees, or a complete journal.

All monetary values are integer euro cents. Do not count a parent receipt and its split components as separate sales. Receipt hashes and opaque order/tab/ split identities identify correction evidence; they do not authorize writes or substitute for original accounting documents. The current correction adapter supports proven simple single payments. Unproven aggregate, split, refunded, or period-correction allocations remain review-only.

Refund dates and signed amounts

Reports use refundReporting.policy: refund-event-date/v1. A sale stays on its original business date; a later refund reduces the refund date's totals. A day with refunds and no new orders can therefore have negative sales and VAT. Keep gross, net, VAT, payment allocations, tips, and deferred gift-card amounts as signed integer cents. Refund totals and counts remain nonnegative.

For example, a EUR 20 sale on Monday and its full refund on Friday contribute EUR 20 on Monday and EUR -20 on Friday. Do not subtract refundsMinor again from grossSalesMinor: that sales amount already includes the refund effect.

Check the response's refundReporting evidence flags:

• legacyTiming means the report includes legacy cumulative refund evidence; it cannot reconstruct missing historical partial-refund dates.
• incompleteEvidence means attribution or other required evidence needs review. Do not treat the report as fully reconciled just because totals exist.

Respect payment-report warnings such as legacy_refund_timing and refund_evidence_incomplete. Never book a corrected allocation when adjustedRows is null. Tips and deferred gift-card purchases remain separate from taxable sales.

Store the report policy and contract version with each import.

Re-imports and reversals

Persist the imported accounting and payment snapshots, period, calculation versions, and applied correction IDs with the import record. IDs alone are not an import-deduplication strategy: undoing a correction removes it from the active set. Compare the new adjusted allocation to the previously imported adjusted allocation. An unchanged re-import produces no change; undoing a correction produces the inverse allocation. If raw sales changed, reconcile the accounting baseline before applying a payment-only reclassification.

Undo requires the selected source payment to remain valid and present. If it was later voided, unconfirmed, removed, or otherwise changed, the undo stays in manual review. These tools remove the allocation transfer only; they do not repair or recreate the original sale, VAT, refund, or provider record.

For example, correcting one EUR 12.60 receipt from Card to Cash moves 1,260 cents out of Card and into Cash. Its 150 VAT cents move between the reporting method buckets while total sales and total VAT remain unchanged. This is an allocation change, not a second sale or a new VAT liability.

Report status

Identify a payment

A receipt hash helps find a receipt and its related payment sources. A tab or parent receipt may contain several payment legs, so a hash alone does not always identify one tender. Inspect the returned source kind, record ID, method, amount, and any tab-split or component identifier before choosing a payment to correct. Do not add parent totals to their component totals.

In Dashboard, eligible members can open payment corrections from Orders or Order search. They can also choose a day or month in Reporting corrections, filter the source payment method, or search for a receipt to choose a specific payment. Review the preview and supply a reason before applying a correction.

Management exports use the restaurant's configured business-day cutoff and preserve the report status and correction evidence. A mismatch in dates, method amounts, transaction counts, or VAT blocks the accounting bundle. Review any export warning before using the result for bookkeeping; a raw view must not be mistaken for an adjusted allocation.

Correct through Management, the Partner API, or MCP

In Management, open Payment corrections, select an authorized restaurant, and choose a business day or calendar month. Search by receipt hash or source ID, filter by payment method, and select the exact payment. Choose its correct method and enter a reason. Review the before and after amounts before confirming. The month view helps find payments; each correction still targets one payment on its business date.

For writes, both OAuth transports require all four approved scopes: fiest.restaurant.read, fiest.accounting.read, fiest.analytics.read, and fiest.accounting.corrections.write. Existing connections must authorize the additional scopes; read access is never upgraded automatically.

On an unchanged retry, batchId and revisionId identify the original operation, while report reflects the current day head. A later correction or undo may have changed that report. Use report.appliedCorrectionIds to find currently applied revisions; the replay's revisionId does not assert that its revision is still active.

For a Management portfolio connection, use get_management_context to select authorized organizationId and restaurantId values, and pass those selectors to each MCP correction call. Use the API's authorized restaurant path and organization_id parameter for the equivalent portfolio scope. Always preserve sourceRecordId exactly as returned, including its sign or tab prefix.

The API and MCP use the same preview and confirmation flow:

1. Use the workspace with scope, startDate, endDate, and an optional receipt hash or source ID query. Select a returned sourceKind and sourceRecordId; never guess a payment leg from a parent receipt hash.
2. Preview with businessDate, the selected source identity, action: correct, toMethodKey, and a reason of at least four characters. To undo, use action: undo and omit toMethodKey.
3. Show the returned before and after reports and obtain the user's approval. Apply the unchanged preview input with its expectedRevisionId, previewFingerprint, expiresAt, confirmed: true, and a new UUID idempotencyKey. An unchanged retry must reuse that key. A different request needs a new key. Previews expire after ten minutes.
4. If the report or source changed, request another preview and approval. Never retry a stale preview by removing its revision or changing its fingerprint.
5. Check the returned report, then read and reconcile both accounting reports again before importing the changed allocation.

Changing or undoing one payment preserves other corrections for the day. The immutable audit history records the reason and actor; original sales stay intact. Current API and Management writes support proven, single-method order and tab payments. Split payments, refunded payments, missing VAT evidence, and aggregate or period corrections remain blocked for review. Correcting a method cannot fill missing accounting evidence or establish bank settlement.