Virtual Terminal, Invoices, and Document Builder

These pages handle three different workflows:

• Virtual Terminal creates a keyed sale or authorization for the selected store.
• Invoices creates and tracks customer receivables for the selected store.
• Document Builder manages invoice and receipt layouts for the organization.

Use the organization and store selectors before starting. Never use Virtual Terminal as a substitute for an invoice when you need to send a balance for later payment.

Virtual Terminal

Virtual Terminal is for card-not-present or manually keyed transactions explicitly supported by the portal:

• phone orders;
• mail orders; and
• keyed in-person sales when a reader is unavailable.

The page requires store.transactions.read, store.transactions.write, and store.products.read for the selected store. Without all three permissions, Virtual Terminal is unavailable, including through a direct link. Store cashiers do not need org.categories.read or access to tax settings: checkout loads only active, Gateway-mapped category names and codes through the selected store's checkout access. A completed sale appears in Sales & Payments and moves inventory like a sale completed at a register.

Catalog lines send only the selected product and quantity. The server resolves the active store-scoped catalog price, tax, deposits, and totals; cart figures before preparation are provisional. Ordinary custom lines and catalog price changes require a persisted server price approval issued by an authenticated manager with store.products.write and their own price-override delegation. The server validates the approval's store, actor, quantity, currency, current catalog snapshot, expiry, and quote identity. Manual lines use the server's General Merchandise tax treatment rather than a caller-selected exemption. Selling a gift-card denomination uses the separate gift-issuance permission and policy, not ordinary manual-price approval.

Key a sale

1. Confirm the selected store and open Store Operations > Virtual Terminal.
2. In 1. Items, search for products by name or barcode and add them to the cart. For an ordinary custom line, enter its description and amount and obtain the required server price approval.
3. Review quantity and the provisional catalog price for each line. Price changes require the same approved override workflow; entering a different number does not change a catalog charge by itself.
4. In 2. Customer & tax, attach the customer or explicitly continue without one when those controls are available to your role. An attached customer's saved tax address and exemptions can affect the quote; a city or state entered under Tax destination overrides that saved destination. With Customer read permission, search the store-scoped customer directory by name, email, phone, or loyalty ID and select the matching profile. Directory search is available even when loyalty prompting is off or the store's loyalty contact input mode is ID-only; that setting governs enrollment, not existing-customer search. With both Customer read and write permission, New Customer checks the selected permitted phone or email first, attaches an exact existing match, and enrolls only after a lookup miss. Names are optional for enrollment; profile editing and marketing consent belong in Customer management. Ambiguous enrollment identities must be resolved there before attachment. US phone enrollment lookup treats ten national digits and the equivalent eleven-digit number prefixed with 1 as the same identity without rewriting saved profiles; if separate profiles match those forms, the identity remains ambiguous.
5. Choose how the card was received: Phone order, Mail order, or Keyed in person.
6. Enter the card number, expiration, and security code only in Peak Gateway's embedded secure card fields. Enter the cardholder name and billing address in the Virtual Terminal's corresponding fields. Do not save card details in notes, screenshots, email, or another customer field.
7. Enter an email or phone under 4. Receipt & confirm when the customer should receive a receipt. Add an order reference that will help staff identify the sale later; the customer sees it on their receipt. Use Internal note for anything only staff should read.
8. Prepare the payment to obtain authoritative pricing and tax for the current selections. If you change an item, customer, destination, tip, reference, or payment detail, obtain a fresh quote. Retrying delivery of the same quote attempt returns its original immutable price, even if the catalog subsequently changes; a new explicit attempt uses current pricing.
9. Choose an action:
   • Charge now completes the sale immediately.
   • Authorize only — hold the funds, capture when it ships reserves the amount for later capture.
10. When secure checkout is ready, select the Retail Charge now or Authorize only button once to submit the quoted payment.
11. Wait for Payment approved or Authorization approved. For an authorization, select Capture now only when it should be completed.
12. Select View in Sales & Payments and confirm the resulting transaction.

The checkout total and Charge / Authorize action appear above the entry form and remain pinned while you scroll, on desktop and phone layouts. Review the amount in that summary before submitting; moving the action does not skip the required customer, billing, card-entry, or quote checks. When an approved result appears, the page scrolls to its existing result card and focuses the approval heading. New sale remains in that result card; the pinned Charge action stays disabled after approval.

If the page reports Payment requested or an unknown outcome after payment dispatch, the original intent remains available separately for status and recovery. It does not lock a new, unrelated cart. Use the original intent's recovery action; never assume an unknown result failed or enter the same purchase as a fresh payment merely to retry delivery.

Hosted-session creation is fenced before Gateway is called: the original intent and a high-severity Action Inbox review item are recorded first. If the create response is lost before a session ID is returned, the original attempt stays pending review and Gateway create is not retried. Do not start another checkout for that purchase or treat local expiry as proof that no session was created. Reconcile the original review; unrelated carts remain available.

A definitive decline of a customer's saved card ends that checkout as failed and releases any reserved reward points. Reopening or retrying the same checkout preserves its original decline; it does not charge the card again. A lost or ambiguous payment response remains in recovery, with its reward reservation retained until the original outcome is known. Older responses that do not establish whether an amount was processed also remain in recovery rather than releasing rewards prematurely.

Where gift-card and card split checkout is enabled, completion keeps one sale with the quoted gift/card amounts and any quoted coupon link. Recovery uses that original quote and transaction; it does not replace the coupon or create another sale.

Apply a gift card, then choose New card or an available saved card belonging to the attached customer for the remainder. Saved cards are selectable only after the server quote permits that remainder; store configuration alone is not enough. A full gift-card payment needs no card and excludes saved-card selection. A permitted saved choice already selected before applying a partial gift is retained.

Changing between saved and new cards, editing card context, or selecting Gift Card again keeps the applied gift reference. Source and context changes invalidate payment authority: the next charge obtains a fresh quote and rechecks saved-card availability before submitting. The confirmation shows both portions and the card Charge button shows only the remainder. Choose Remove gift card or explicitly select Credit / Debit to return to a card-only sale. Card-entry fields stay mounted while choosing tenders.

For saved-card remainder, the browser submits only the owned payment-method identifier and quote version, not a hosted checkout session. The backend authorizes the card remainder, redeems the gift card, then captures the authorization; it never replaces that sequence with a direct card sale. New-card remainder continues through hosted secure card entry. Do not blindly retry a lost authorization, gift redemption, or capture response, or recreate that purchase as another sale: use the original intent's status and recovery evidence. An unknown outcome is not a decline.

Gift-card allocation, mixed-tender availability, reward combinations, saved-card availability, and authorization eligibility come from the server quote. A gift denomination is not merchandise or a tip: the server excludes it from reward discounts and tax basis and binds issuance to the quoted denomination, not the complete basket total.

Invoices

The Invoices navigation entry is available to roles with invoicing read, write, or administrator access. The list itself is scoped to the selected store. Actions require narrower permissions:

• invoicing.invoices.write creates and edits drafts, issues and sends invoices, and manages saved invoice items;
• invoicing.payments.write records payments, creates payment links, and handles eligible refunds; and
• invoicing.invoices.admin enables invoice administration such as voiding and defaults management.

Find and track an invoice

1. Confirm the selected store and open Store Operations > Invoices.
2. Search by invoice number, customer name, or notes.
3. Filter by status: Draft, Sent, Partially Paid, Paid, Refunded, Overdue, Uncollectible, or Voided.
4. Review the due date, total, paid amount, and outstanding balance.
5. Select the invoice to open its detail.
6. In the detail, review:
   • invoice status, customer, due date, line items, discounts, delivery fee, and totals;
   • Delivery status, including destination, provider outcome, failure reason, and attempt count;
   • Payments and any recorded refunds;
   • Activity Timeline for status changes and other invoice events; and
   • Last Sent and first-viewed information when recorded.
7. Use PDF to preview or download the customer document.

Custom Party addresses retain their street lines, city, region, postal code, and country when the invoice layout is frozen for sending or link issuance. The customer page and PDF use that frozen address, so later template edits do not change an already-shared invoice.

The customer invoice shows its line items before totals, then the payment schedule. Remaining balance and Due now are distinct server-calculated amounts; Next payment shows its scheduled amount and due date. Unpaid invoices keep plain schedule rows without progress bars. Once payments or credits are recorded, the invoice and affected stages show accessible progress; cash paid and credited amounts remain distinct, and excess credit appears as account credit. The payment amount choices and single Pay button appear separately below the invoice document. A future balance does not make the full outstanding amount due now.

New and repriced draft invoices round each extended line subtotal, line discount, invoice discount, tax, and delivery fee to the currency's minor unit using half-up rounding (a half cent rounds up for USD), matching POS receipts. Tax uses the rounded taxable amount after discounts; invoice-discount allocation conserves whole cents across lines. The total is exactly subtotal minus discounts plus tax and delivery. For example, $10.05 less a 10% discount is $9.04 taxable; at 2% tax the invoice is $10.05 − $1.01 + $0.18 = $9.22.

The editor preview, saved invoice, customer payment page, and PDF display server figures, not independently calculated totals. Payment collection uses the stored invoice balance or admitted payment-schedule amount. Existing issued invoices and payment histories are not repriced or silently corrected by this rounding change.

When converting a historically approved quote with sub-cent stored components, its quoted tax is retained even when rounding those components already equals the approved total. Where an amount adjustment is needed, a non-negative fixed discount is derived from rounded subtotal, quoted tax, delivery fee, and the approved collectible total. A QUOTE_ROUNDING_PRESERVED event records the original policy, converted discount, and approved total. For example, an old untaxed $10.05 quote less 10% approved $9.05; its invoice displays $10.05 less a fixed $1.00 discount = $9.05. A historical half-quantity $20.11 line with $0.8547 frozen tax converts as $10.06 subtotal + $0.85 tax = approved $10.91, without repricing tax to $0.86. Newly calculated quotes use the ordinary rounded-component rule instead.

An unchanged converted historical quote retains its accepted tax snapshot and discount through draft saves, the live editor preview, the issue preview, and ordinary issuance. The live preview checks the same prospective saved aggregate while retaining normal catalog, ownership, and tax-intent validation; edited price inputs use normal pricing. Previously repriced draft tax is restored from the quote before issuing.

Historical conversion never introduces a negative discount. A customer-favorable reduction is allowed only when the unrounded stored subtotal minus discount plus tax and delivery rounds to the approved total, and the reduction fits the component-rounding bound. That bound is half a currency minor unit for each line subtotal, line discount, line tax, and the delivery component, summed and rounded up to whole minor units. The invoice uses zero invoice discount and never exceeds the approved amount. The QUOTE_ROUNDING_CUSTOMER_FAVORABLE event records approved/final amounts, raw and rounded components, and the bound; unreconciled or excessive drift blocks conversion. For example, an old $10.004 subtotal plus $0.004 tax approved $10.01; its invoice displays $10.00 subtotal, $0.00 tax, $0.00 discount, and a $10.00 total.

A one-line quote with raw subtotal $10.084, line discount $0.006, tax $0.5039, and delivery $0.004 approved $10.59. Its rounded components are $10.08 − $0.01 + $0.50 + $0.00 = $10.57. The two-cent customer-favorable reduction is within its four-component $0.02 bound and is audited, rather than blocking conversion.

When this customer-favorable reduction affects fixed payment terms, later stages are reduced first and exhausted zero-value stages are omitted. Surviving stage labels and due dates remain unchanged, and no stage amount increases.

Linked credit notes allocate the original invoice line's rounded net amount and frozen tax cumulatively across credited quantities. Crediting both untaxed half-quantity lines at $19.99 therefore clears a newly rounded $20.00 invoice, rather than leaving a cent due. For historical invoices that rounded those same lines together to $19.99, stable line-order cent allocation preserves that original amount instead. Credit-note subtotals, tax, and totals sum from the credited components; existing invoice, balance, line-value, and quantity caps still apply.

Historical line-cent allocation is independent of document-level delivery fees and invoice discounts. Two old $9.995 line snapshots plus $1 delivery form a $20.99 invoice, but the line credits total $19.99, not $20.00. That clears the balance if delivery was already paid, or leaves exactly $1 delivery otherwise. Discounted documents retain the same invoice-total and remaining-balance caps.

Historical aggregate-rounded tax is conserved alongside the original line totals. For example, two $0.10 lines with old $0.005 tax each on a $0.21 invoice produce a full credit of $0.20 subtotal plus $0.01 tax, not $0.02 tax. Remaining tax cents use only still-creditable quantity and gross capacity; tax cents committed by a previous credit, including a zero-gross allocated row, are retained.

Explicit price-adjusted credits retain their existing tax and amount rules outside the original-price frozen-tax limit, so their tax cannot block a later credit on an unrelated line. Original-price tax cents are tracked per prior row, including when the same invoice line also has price-adjusted history. All actual prior credits still count toward the unchanged invoice, balance, line-value, and quantity caps.

If immutable original-price legacy credits already committed more tax cents than the invoice's old aggregate rounding, those cents are retained without rewriting history or creating signed tax. No further frozen tax is credited, but otherwise valid later credits remain allowed within the unchanged gross, balance, line-value, and quantity caps.

Fully credited historical taxable rows can also leave an unclaimed rounding cent. It is not transferred to exempt rows and does not block an otherwise valid exempt credit. Already committed gross cents are likewise retained even when they exceed the old rounded line aggregate; unused line capacity can be reduced down to, never below, committed amounts. Valid unlinked adjustments against remaining delivery still use the ordinary invoice and balance caps.

For prior credit notes with historical sub-cent line values, subsequent linked credits use the cents actually committed by each credit document. Those cents are allocated in stable line order without editing the earlier note. A $3.3330 historical line on a $3.33 credit note therefore leaves $6.67 creditable against a $10.00 original line, not a spurious over-cap error. Existing credited cents also take precedence when allocating the remaining cent of a historical aggregate-rounded invoice.

If a historical credit has already granted the next rounding cent, a small additional original-price quantity can contribute zero while another line makes the new credit note positive. That earlier cent is carried forward, not credited twice; the final quantity credits only the amount still owed. Original quantity/value caps and the requirement for a positive credit-note total still apply.

Invoices created from a quote show Created from Quote and its number. In the merchant portal, select that number to return to the source quote; the converted quote links back to the invoice by number (or to the draft before an invoice number is assigned).

Customers revisiting an accepted quote see its conversion date and the invoice's current outstanding balance. View / Pay Invoice opens the numbered invoice when it is payable; after full payment or voiding, the link becomes View Invoice. The original quote total remains unchanged. The customer invoice also identifies the source quote by number.

A successful send is queued for delivery; it is not proof that the customer received it. Return to Delivery status and check the provider outcome. Authorized invoice writers can retry a delivery marked failed.

Invoice delivery retries refer to the original durable delivery ID. If a send response is interrupted before that ID is visible, retry the same send identity instead of starting another delivery. Queued or processing delivery remains pending; only the provider's delivery result confirms receipt.

Invoice detail and list reads provide server-calculated action availability for issue, send, void, record payment, payment link, refund, and credit note. Refund availability and tender-specific capacity account for existing refund reservations; invoice credits and payments are not treated as interchangeable. A pending payment outcome is shown by the server's payment admission state, rather than inferred from client status or a locally calculated balance. Actions still revalidate current state when submitted.

For a full card-payment refund before the processor batch closes, the invoice refund workflow reverses the original payment with a void. After settlement it uses a refund. A partial card refund must wait until today's batch closes; the invoice reports that requirement rather than submitting an unsupported partial reversal. A pending or unknown reversal keeps its original identity for reconciliation. Do not start another refund while that outcome is unresolved.

When confirmed refunds reduce the invoice's net applied payments to zero, its status becomes Refunded and its collectible balance becomes zero. Original totals, payments, and refund history remain unchanged. It is not eligible for payment links, reminder or overdue collection, or Auto-Pay notices. A partial refund preserves the existing rule: returned applied payment funding increases the remaining receivable while other net payments remain.

Collection reminders are checked again under the invoice lock immediately before queue admission. A message already accepted by the email queue before the refund commits can still be delivered; refunding does not recall an accepted message.

An invoice administrator can explicitly select Reopen invoice on a refunded invoice. Confirming restores the original receivable less recorded credits and net payments, using the retained payment schedule. Reminder and overdue eligibility resumes and existing customer links can accept payment; reopening itself sends no message or payment. Existing historical refunded/open invoices are not silently rewritten.

A single keyed send can queue both email and SMS. Its response identifies only that send's durable delivery rows, including their IDs and statuses. Retrying the same identity preserves both rows and rejects changes to recipients, customer name, message, or channel selection; use a new send identity for a different delivery request.

Completed actions recorded before delivery receipts were included still replay with their original identity and financial snapshot. For an older send whose exact delivery rows cannot be proven, the response explicitly reports deliveryIdentityKnown=false and an empty receipt list. This is an unknown delivery association, not proof of failure or permission to retry another delivery from the invoice's history. Keep the original send identity and use delivery-history readback for investigation rather than automatically sending again.

Invoice reads preserve the stored historical customer identity. If that snapshot is corrupt, detail, list, and assistant search report an explicit integrity error instead of substituting the customer's current name or contact details. Valid older snapshots still support absent fields and legacy names; an explicitly empty or null field is not replaced with live customer data. Corrupt records require investigation rather than silently changing the document.

Hosted invoice checkout may prefill the customer's name, email, phone, and billing street from the details already captured on the invoice. Those values stay with the original hosted checkout attempt: retrying or resuming it does not refresh them from the customer's current profile, and existing customer details in checkout are not overwritten. These are suggestions for checkout only; they do not verify who is paying or authorize a charge.

On the customer invoice, select Pay due now or an available Pay full balance option in the payment amount card. The single Pay button follows that selection and opens secure hosted checkout. Full-balance payment requires invoice policy to permit paying ahead and the server to admit that amount safely; an existing session may leave only its verified original amount available until safe replacement can be proved. Permitted custom amounts are available under Pay a different amount. An existing checkout for the same amount is reused without a separate reopen or continue choice. Opening checkout does not itself mean a payment was submitted. If checkout could not be confirmed, use the same amount's Pay action to retry delivery of the original request; do not assume an interrupted response means no checkout exists. Any support reference is copyable, while internal error codes and HTTP status are not displayed on the customer page.

When no amount is currently due and a future scheduled payment is available, the scheduled choice is labeled Pay next payment, not Pay due now. Custom amounts must be positive, use the invoice currency's precision, meet the displayed minimum, and not exceed the remaining balance. The server revalidates these bounds and payment policy when checkout starts.

If the only safe action is resuming a verified existing checkout whose original amount differs from the current scheduled and full-balance amounts, the invoice shows one Pay button for that exact original amount, without an amount chooser or custom input. This preserves the existing checkout's immutable amount even if the merchant has since raised the minimum or disabled new custom payments; it does not authorize a new amount. Required authorization, submitted-payment uncertainty, and provider funding checks still block unsafe payment admission.

After returning from hosted checkout, the customer invoice refreshes its server status every 2.5 seconds while the returned payment is unresolved, for up to one minute. The same bounded refresh applies when payment admission reports a pending outcome. Refreshing stops when the invoice is paid or terminal; a recorded partial payment resolves the hosted return unless another outcome remains pending. Refresh remains available after automatic checks stop and does not start or replace a payment.

The public invoice page does not enroll, replace, remove, select, or newly charge saved cards, and does not create Auto-Pay authorizations. Those invoice-link setup and authorization operations have been retired. New customer invoice payments start through hosted checkout only. Card saving is off for this guest checkout because a verified customer binding and supported guest-save capability have not been established; the invoice does not send a save-card request flag. An invoice requiring a saved-card authorization directs the customer to contact the business rather than bypassing that policy. Merchant payment-profile and Auto-Pay settings remain separate.

Revoking a payment link remains a safety operation even for a corrupt snapshot: active tokens and pending deliveries are revoked. If the refreshed document cannot be read, the integrity error explicitly confirms that the payment link was revoked; it does not mean that the old token remains usable.

Use a card saved during hosted invoice payment

For a merchant-bound invoice, a card saved with stored-payment consent belongs to the invoice's actual customer. View the masked card in that customer's Payment Profile and the invoice's Customer saved cards section. Card entry remains in Gateway's hosted checkout; this does not create another public card-enrollment link.

With invoice payment read and write access, select an eligible saved card, review Use next scheduled amount or enter a positive Charge amount no greater than the outstanding balance, confirm use of the stored consent, and select Charge saved card now. This is a merchant-initiated card-on-file payment, not a manual payment-history entry. A pending or unknown result is not a decline: use Refresh saved-card payment status and resolve the original outcome before taking another payment.

If delivery was interrupted, Retry original saved-card payment sends the original payment identity, saved card, and amount again; changing the form does not change that retained request. This also recovers a request that never reached the server. The server returns the original outcome or checks whether the original terms can still be admitted; changed balance or card availability can produce a confirmed rejection instead. An absent status record or a generic error does not establish that the original payment failed. Do not start another payment until the original has a confirmed terminal outcome.

Saving a card does not create an Auto-Pay mandate or authorize scheduled charging. When Auto-Pay is enabled for the organization, authorized invoice writers can separately enable optional Auto-Pay for the invoice and record the customer's explicit authorization for the selected eligible saved card and current schedule. Review the displayed authorization terms; schedule or card changes require renewed confirmation.

Automatic scheduled charging remains unavailable pending #5590, even after an Auto-Pay authorization is saved. Continue collecting payments manually; selecting a saved card or saving an authorization does not enable automatic dispatch.

Create and send an invoice

1. Select New Invoice.
2. Choose the customer and due date.
3. Add each product, saved invoice item, or manual line. A manual line must have a category.
4. Review quantity, unit amount, discounts, delivery fee, terms, footer, and notes.
5. Save the draft and open its detail.
6. Select Send.
7. Confirm the customer name and enter at least an email address or phone number. Add a message if needed.
8. Select Issue and Send Invoice for a draft, or Send Invoice for an already issued invoice.
9. Reopen the invoice and verify its status and delivery result.

Draft creation is separate from issue and delivery: a draft can be saved without a due date or delivery contact. Issuing requires valid invoice lines and a positive server-calculated balance; sending requires an eligible issued invoice and a recipient. Invoice and quote editors obtain canonical totals, tax, discounts, and payment-stage amounts from the server. Product-reference invoice lines use the selected store's currency and the server-authorized catalog price, rather than a price copied from a client cache.

Assistant invoice creation and updates verify the document's new financials before confirming the save; verification does not read an older saved version or initiate a payment. Normal detail refreshes after the save continue to check already-submitted payment and refund outcomes.

On iOS, Save offline retains draft-only intent: synchronization creates the draft without issuing it or reducing stock. Submit online retains a separate explicit issue choice for later synchronization if interrupted. Older queued records without a known issue choice remain drafts and keep their original invoice identity.

Android's online create-and-send flow saves the draft first, then submits authenticated POST /invoices/{invoiceId}/issue-and-send in the existing scoped invoicing route. The server issues an eligible draft and queues delivery in the same transaction; an already issued invoice is delivered without issuing again. This intent uses the original logical send action key and body fingerprint, including original deterministic delivery IDs. A key previously submitted to /send replays its historical receipt before any issue, stock movement, or new delivery, even after switching endpoints. The existing /send endpoint remains delivery-only: drafts use canIssue, not canSend. Creating without contact or synchronizing an offline draft never implicitly issues or sends it.

Draft and quote editors use POST /api/v1/orgs/{orgId}/invoicing/invoices/draft-preview?storeId={storeId} with invoice-write authorization and the same store-scoped invoice creation intent. The body store must match the authorized query store. Its response supplies the currency, subtotal, discount total, delivery fee, tax total, collectible total, per-line financials, and resolved payment schedule. Preview does not save a draft, create a walk-in customer, or repair tax identities. Without a selected customer it calculates tax at the store address with no customer exemption. An existing draft preview can supply invoiceId and each item's sourceLineId to reuse that draft line's authorized category while recalculating edited amounts; foreign draft or line references are rejected.

For invoice drafts, the server normalizes submitted line quantities to four decimal places with HALF_UP for both preview and save, rejecting quantities that normalize to zero or below. Use the preview's canonical quantity and per-line financials in the editor; do not round the raw input or recalculate those values locally.

New quote draft quantities are normalized by the server to four decimal places with HALF_UP in preview and draft create/full replacement and line add/update/delete, before validation, tax, and line financials; quantities that normalize to zero or below are rejected. Use the quote preview's canonical quantities and per-line financials rather than rounding raw input or calculating them locally. This applies only to new quote draft input: published or accepted quote snapshots and existing quote-to-invoice conversion behavior remain unchanged.

Catalog invoice lines can submit only posProductId (the POS product UUID) and quantity. The server resolves an active product in the selected organization and store, derives its name, category, SKU, price, and store currency, and ignores caller-authored catalog description, category, and unit amount. A conflicting currency is rejected. Manual lines still require a description, unit amount, and authorized product/category or billing-code attribution; line discounts, invoice discounts, tax exemptions, and schedule timing remain server-validated. Relative payment dates remain unresolved until issue, rather than being replaced by a client guess.

Draft replacement, line addition, and line updates carry the same explicit posProductId catalog intent and resolve the current catalog price on save as on preview. An inventoryItemId without posProductId retains the existing manually entered price policy and uses the inventory product for tax attribution only. Editable draft previews honor the submitted exemption toggle, including removal of a previously saved manual exemption; unchanged issue previews explicitly preserve the saved manual intent. Quote previews use the quote's own save intent rather than introducing catalog pricing that quote writes do not apply.

Payment-schedule edits for existing drafts and issued invoices use POST /api/v1/orgs/{orgId}/invoicing/invoices/{invoiceId}/schedule-preview?storeId={storeId} with the schedule-save intent (currency, milestones, optional allowPartialPayments). This preview resolves stages against the stored collectible total and original issue date without recalculating tax or changing the document. It preserves payment-locked stages and rejects foreign stage IDs, invalid timing, and schedules that do not cover the total. Saving revalidates under the invoice lock and refuses to change the schedule while a payment outcome is pending.

Accepted payment methods in Invoice Settings controls the defaults for new invoices. Each invoice stores its own selection; the draft editor can override it without changing the merchant defaults or existing invoices. Uncheck Card to disable online payment. Customers can still view the document, but cannot open a hosted checkout. The ACH option is disabled because invoice checkout is currently unavailable for ACH: Gateway must first provide authoritative tender, pending/settlement, failure and bank-return reporting. A saved ACH preference never authorizes or enables ACH charges. Card checkout also requires current Gateway merchant policy and capability authorization; invoice settings never grant payment capabilities. Currently, Gateway must prove an explicit operational card-not-present route. Default-only routing remains unavailable until Gateway publishes its effective location routing authority (integration issue #5630), even if Card is selected in Invoice Settings. Changing that selection does not create Gateway authority. Invoice document links, delivery and reminders remain available independently of online card availability. With payment-management permission, Payment Link still generates or copies the view-only invoice link when online methods are disabled; opening that document never overrides the checkout authorization checks. Scheduled, full-balance and custom payment choices remain subject to the current server capability projection; invoice policy alone does not authorize replacing an unresolved or funded checkout.

Reuse an invoice configuration

From New Invoice, open Reusable templates to manage configurations for the selected store. These are separate from PDF layouts in Document Builder.

• Use Save current invoice as template to copy the current products/services, descriptions, payment structure, terms, notes, discounts, delivery and tax intent into an isolated editor, or start with New template.
• Give it a Template name and choose Save template. Edit and Delete are explicit operations; stale changes require reloading the saved template before another write.
• Use copies a saved configuration into the current invoice without changing its customer. Invoice edits afterward never update the template or merchant defaults.
• Optional Starter templates provide Contractor / Project, Professional Services and Standard Invoice structures. Customize them with real products/services and prices; starters are not mandatory defaults.

Leading fixed amounts stay fixed and percentages are calculated against the new invoice total. The final stage is the remaining balance. Calendar dates are saved as days after invoice issue, and overall due timing is reused relative to the new invoice. Tax is calculated from the selected store, product/category and customer at invoice save; templates do not freeze tax totals or reuse customer exemption certificates.

Reminder configuration can inherit the current merchant cadence separately for each new invoice or copy an explicit template override, including reminders disabled. Later invoice changes do not mutate the template or organization settings.

Collect and reconcile an invoice

With payment write access, open an eligible invoice and use:

• Record Payment to record an amount, received date, method, and reference; or
• Payment Link to create a link for the customer.

After collection, confirm that the Paid and Outstanding amounts, invoice status, payment row, and activity timeline agree. Use Refund only when the invoice and payment are eligible. After resolving a definitive provider rejection, a new refund request can use the released balance. If the provider outcome is uncertain, the amount remains reserved until reconciliation; do not submit another refund for it in the meantime. Invoice administrators can use Void when the invoice is in a voidable state.

Action buttons and refundable capacity by tender come from the current server invoice projection. Payment admission is shared across saved-card, hosted-card, gift-card, manual, and Auto-Pay operations. The server retains each attempt and prevents conflicting payment rails from collecting the same balance while an outcome is pending. Retry an interrupted attempt with its original identity; a distinct explicit attempt has a new identity. Pending work on one invoice does not prevent creating or editing another invoice.

An interrupted hosted invoice checkout creation is not evidence that a payment was submitted. The customer can select Pay to continue the original checkout; the server also recovers it automatically in the background. Recovery looks up the original CREATE idempotency key and binds a matching session. If no session is found, it replays only the original sealed CREATE with that same key and amount, so concurrent or late responses converge on one checkout rather than a new payment identity. An unavailable lookup or replay keeps the original balance fence and shows a calm try-again message, not a request to contact the business for payment review. Current authorization is still required before replaying CREATE. Submitted or funded payment uncertainty remains separately fenced and is never treated as failed or replaced because time passed.

If opening checkout times out or loses its connection, the Pay button becomes available immediately with a plain retry message; background status checks do not keep it on Please wait…. Retrying the same invoice link and amount reuses the original request identity and resumes its existing hosted session, even if the server completed checkout creation after the browser stopped waiting. A newer retry cancels older status observations so late responses cannot replace the current attempt.

Retry payment delivery reuses the original manual payment's amount, currency, received date, method, reference, and request identity after reload. Those fields stay fixed for a retry; the current outstanding balance is not a replacement request. Older recovery records without those fields require exact original-detail reentry before replay. Gift-card codes are never stored with browser retry records.

Gift-card recovery first inquires for the original scoped redemption. A confirmed debit is applied without redeeming again, even if the card expires, gift-card acceptance changes, or the store's payment binding changes after submission. The original payment location is retained before submission and is never replaced during retry. An uncertain inquiry remains pending; new redemptions still require current card and tender eligibility.

A Gateway insufficient-balance rejection is not by itself confirmation that no gift-card debit occurred. The system checks the original redemption record: a found redemption is applied normally, while only a successful check confirming no redemption marks that attempt failed and makes the invoice available for another payment. If the check is unavailable or the provider response is otherwise uncertain, the payment remains pending for recovery; do not submit another payment until its outcome is resolved.

Each settled invoice installment is a purchase, with its actual tender retained. Partially refunded purchases remain in gross customer spend and visit totals; their refund entries are tracked separately. Gateway invoice receipts use the persisted completion event's time, including for captures made after authorization. Eligible Loyalty earning uses the amount actually applied to the invoice, excluding automatically refunded excess. Historical or racing Loyalty awards whose original amount cannot be verified require review: they are not automatically activated, reversed, or recalculated.

On a customer's invoice link, one payment area and one Pay button are used on desktop and mobile. Opening a different invoice link shows its loading state instead of the previous invoice, and late responses from the previous link cannot change the current invoice or redirect it into the old checkout. Leaving a link cancels that page's pending status checks, not a payment already sent to the provider. If a checkout result is uncertain, confirm the invoice's payment history and outstanding balance before starting another payment.

Automatic checkout delivery recovery is bound to the original invoice link, currency, and displayed amount in currency minor units, not just the Scheduled or Full Balance option name. A changed due amount or a regenerated link never silently adopts the old request identity. Unmatched recovery records remain separate; a newly scoped request still requires current server admission or verified safe replacement. Browser persistence stores a hash of the link scope, not the bearer token.

Historical saved-card payments remain available for status inquiry and exact original-request recovery. The retained public payment-profile delivery operation accepts only a previously recorded durable request identity and immutable body; an unknown identity is rejected before a new dispatch. Recovery never enrolls a card, creates an Auto-Pay authorization, or turns the current invoice balance into a new saved-card charge. Prior outcome and required-policy reads remain available independently of new hosted-payment admission.

Customer SDK migration for this intentional breaking release:

• PublicAccountInvoicePayload.autoPayRequired is now required. Consume the server's policy evidence rather than defaulting an absent value to false; missing evidence must not authorize new checkout. REQUIRED policy does not become optional when enrollment or the dispatcher is unavailable.
• payCapabilities.resumableAmount is a required nullable amount in the invoice currency. A non-null verified amount can enable one fixed Pay action when ordinary options are empty; use the existing resumeHostedCheckout: true request without option or amount. It is not permission to submit a new CUSTOM amount, and a retained original request must keep its original scoped identity and body.
• Remove calls to PublicInvoiceAutoPayApi.authorize and its retired authorization request/response models. Public invoice links no longer create Auto-Pay consent.
• Remove calls to PublicInvoicePaymentProfileApi.setup, setupStatus, and remove, and the retired setup/removal request/response models. Do not substitute another saved-card enrollment or removal route.
• New public invoice payments use the existing invoice Pay hosted-checkout flow. The retained saved-payment operation is recovery-only for an already recorded immutable request; it is not a replacement for new saved-card charging.

Refreshing an invoice link retains the provider payment identity. If a checkout is marked VOIDED but Gateway inquiry cannot prove a full reversal, the same invoice does not automatically start a replacement debit. Contact the business to reconcile the original attempt before retrying; a status label alone is not proof that no funding remains.

For a refreshed invoice link, the server can authorize replacing a verified unfunded checkout whose return link is obsolete. Replacement cancels and confirms closure of the original session before creating another; saved-card and other rails stay fenced during that process. The browser removes a retained checkout identity only when the server identifies that original request or its alias as ended, never merely because time passed or a response was interrupted.

The public invoice-message POST has been retired, along with the customer SDK's postMessage operation. Its former success response never stored or delivered a message. Invoice viewing, payment, and quote operations remain available; contact the business through its established contact channel instead of treating an API echo as delivery. Integrations must remove calls to the retired operation when adopting the breaking customer SDK release.

The Export receivables panel is organization-wide even though the invoice list is store-scoped. Choose a date range and use Download CSV preview for a local check. Authorized invoice writers can also Generate export and review its status and row count under Recent exports.

Document Builder

Open Store Operations > Document Builder to manage layouts shared by the organization. The page is feature-gated and requires invoicing access. It is not tied to the currently selected store.

The selected invoice layout is used by the editor preview, customer invoice/payment page, and downloadable PDF: saved row order, From / Bill to placement, section visibility, spacing, and table columns are retained while invoice data is populated. Select a saved layout on invoice detail before sending; the first send or public payment-link issuance stores the layout with the invoice, so later template edits or default changes do not redesign a document already shared with a customer. Direct payment links use the organization's current default. Older invoices without a saved layout snapshot continue using Invoice Defaults or the active custom invoice layout until their next send or link issuance freezes it. This also applies to invoices converted from quotes.

The sent layout's Edit layout action is disabled because it represents a fixed snapshot, not an editable live template. Manage templates in Document Builder for future invoices.

For a Party (address block) with Populate from: Custom (enter manually), enter Address line 1, optional Address line 2, City, State, ZIP, and optional Country. These are the same structured address fields used for organization locations. Street lines appear separately, followed by City, State ZIP; empty parts are omitted in the canvas, customer page, and PDF. All address parts are optional. Older saved templates load their original address into line 1 and save structured fields when edited; already-sent invoice snapshots retain their original address text unchanged.

Structured customer addresses use the same street-line and City, State ZIP layout as the sender; historical plain address strings remain literal. Label/value text rows such as Payment status: and Terms: are hidden when their value is absent or blank, consistently in the canvas, customer page, and PDF.

Until you explicitly choose a different layout for an invoice, sending resolves the organization's current default from Invoice Settings on the server. Invoice Settings is the only place that stores the default invoice layout; Document Builder designs layouts and shows which one Invoice Settings selected. With no custom selection, the Standard Invoice layout is used. A temporary preview fallback while layouts load—or when loading fails—is never sent as an explicit template choice.

Creating a direct payment link refreshes the invoice's saved layout. If that refresh fails, the new link stays available to copy; use Retry saved layout to reload it without creating another link. Sending, PDF preview, and layout editing remain disabled until the saved layout is refreshed.

Older partially configured blocks retain their authored text and settings while missing fields receive the existing block defaults; an unsized legacy logo is not resized. Page-break blocks remain visible and selectable in the editor, while the PDF honors the actual page break.

The audit timeline retains the layout-snapshot event without duplicating its template or inline-image payload; the invoice's dedicated saved-layout response supplies the document.

Custom-template invoice emails are branded delivery notifications rather than a second invoice design: the template logo and accent accompany the invoice number, outstanding amount, due date, and View / download invoice link. The link opens the saved layout and its PDF. Plain-text email remains available. Built-in/no-custom-template emails retain their existing presentation.

In Store Header & Logo, choose Small, Medium, or Large. Newly inserted headers and newly configured logos start at Medium; existing logos without a saved size keep their previous size. Images keep their aspect ratio without cropping or stretching. Use HTTPS image links or inline PNG/JPEG data with matching raster signatures, up to 2 MiB decoded; SVG and other data types are not accepted.

PDF downloads and PDF previews first request PNG/JPEG from linked image hosts and inspect the returned bytes, not the filename. WebP (VP8, VP8L, and VP8X, including bounded animation frames) responses are converted to a static PNG; unknown formats are rejected. Linked responses are limited to 2 MiB of streamed bytes. Both linked and inline images are limited to 4096 pixels in either dimension, checked from their headers before decoding; animated WebP canvas and frame dimensions are checked too. Image requests, including response bodies, are bounded to ten seconds. If portal policy blocks a remote-host fetch, a dedicated image worker performs the same bounded, credential-free download under its own image-fetch policy; the portal's connection policy is unchanged. The worker accepts only PNG/JPEG/WebP response content types and hosts must permit anonymous cross-origin access. Original response bytes remain bounded before image decoding, including metadata that would disappear during conversion. Private, expired, non-CORS, oversized, or otherwise unavailable images produce a visible Image unavailable placeholder, and a warning identifies the template (or invoice for a sanitized public layout) without logging the image URL. The rest of the invoice remains available.

Under the existing Settings tab, Branding offers Booking's accent presets and a custom six-digit HEX color. Enable the accent separately for the header, line-item table header, totals/balance area, and footer. The document background stays white and text contrast is chosen automatically. Removing the accent restores the original template styling. Branding never changes amounts, payment terms, customer records, or payment processing.

The current builder exposes:

• Invoice templates used by invoice PDFs; and
• Receipt templates used by hosted, email, and thermal receipts.

To update a layout:

1. Open an existing template or select New Template.
2. Choose the document kind and name.
3. Edit the existing blocks and use the live preview.
4. Add every section or receipt token identified as required.
5. Select Preview PDF and inspect the sample output.
6. Select Save. Saving a built-in template creates an editable copy rather than changing the built-in layout.
7. For an invoice layout, open Invoice Settings, choose the default PDF layout, and save. For receipt layouts, return to the builder list and select Set default when the template is valid and eligible.

The list identifies built-in, default, active, and preview-only states. Duplicate a template before making a substantially different version. Do not delete the active layout until another valid default is ready.

For transaction-level verification after a keyed sale, use Sales & Payments. For terminal or payment-provisioning failures, follow Terminals and Troubleshooting.