Post nightly Clover sales into QuickBooks as one summary receipt

Every night at 2am in the merchant's local timezone, roll up yesterday's Clover sales into a single daily summary Sales Receipt in QuickBooks Online. This is the classic Commerce Sync / Synder replacement pattern: deterministic, no judgement, every field is a known mapping.

Trigger: cron at 2am in the merchant's timezone. Compute the target date as (now - 1 day) in that timezone, then convert to the merchant's local midnight-to-midnight window in epoch milliseconds for Clover filter expressions.

Step 1 — pull yesterday's data from Clover. Call List Orders with a filter of modifiedTime>=<startMs> and modifiedTime<<endMs> and state=paid (page with limit=1000 and offset until fewer than limit come back). For each order, either use expand=lineItems,payments,discounts on List Orders, or fall back to List Order Line Items per order when the nested cap of 100 is hit. Call List Payments over the same time window to capture the full tender picture including tips. Call List Refunds for card refunds and List Credits for manual (unreferenced) refunds, both over the same window. Call List Tax Rates once to resolve tax rate ids to names and rates.

Step 2 — aggregate. Clover monetary amounts are integers in the smallest currency unit (cents for USD); convert to decimals for QuickBooks by dividing by 100 and rounding to 2 decimal places, then reconcile the summed rounded amounts against the raw cent totals so a summary line absorbs any 1-cent rounding drift. Compute: gross product sales (sum of line item price*qty before tax and discounts), total discounts (order-level plus line-item), sales tax collected grouped by tax rate id, tips (payment tipAmount sum), and payments grouped by tender type (cash, credit card, gift card, and any others the merchant uses).

Step 3 — build one Create Sales Receipt in QuickBooks with TxnDate = yesterday. Line items: one positive line per income account for gross product sales (defaulting to a single 'Clover Sales' income account, with the account mapping exposed as a customization knob so the merchant can split by category later), one line for tips going to a tips-payable or tip income account, one negative line for total discounts, and sales tax collected as its own line pointing at the tax-liability account (do not use QuickBooks' automatic tax calc, since Clover already computed it). Set CustomerRef to a generic 'Clover Daily Sales' customer that the workflow creates on first run if missing.

Step 4 — record the tender split against deposit accounts. Because a single Sales Receipt has one DepositToAccountRef, either (a) post one Sales Receipt per tender group with DepositToAccountRef set to that tender's mapped deposit account (cash drawer for cash, undeposited funds or a credit-card clearing account for card, gift card liability for gift card), all sharing the same TxnDate, or (b) post one combined Sales Receipt to Undeposited Funds and then create matching Transfer entries per tender to the correct deposit accounts. Default to option (a): it maps 1:1 to how Commerce Sync writes the day and reconciles more cleanly against the bank feed. Expose the per-tender deposit account as a customization knob.

Step 5 — refunds. If List Refunds returned any card refunds for the day, call Create Refund Receipt in QuickBooks with TxnDate = yesterday, the same generic customer, refund line items mirroring the Sales Receipt structure (product refund line, tax refund line, tip refund line if applicable), and DepositToAccountRef set to the mapped card deposit account so the refund reduces the same bucket the original sale hit. Do the same for List Credits (manual refunds) against the cash deposit account by default.

Step 6 — idempotency and reporting. Use a stable external key like clover-daily-<merchantId>-<YYYY-MM-DD> stored in the DocNumber or PrivateNote of the Sales Receipt so a re-run for the same day updates rather than duplicates. Verify: sum of Sales Receipt line totals minus refund receipts equals Clover's net sales for the day, and total tender deposits equal Clover's payment totals minus refunds. Fail loudly (do not post) if the reconciliation is off by more than one cent per rounding step.

Customization knobs to expose to the merchant: (1) run time and timezone; (2) which QuickBooks income account(s) map to Clover product sales, with optional per-category mapping; (3) which deposit account each Clover tender lands in (cash, credit card, gift card, plus any custom tenders the merchant defines in Clover); (4) which tax-liability account receives sales tax; (5) which account or item receives tips; (6) which customer name to use for the daily sales summary.

Operations used: Clover List Orders, Clover List Order Line Items (fallback when expand caps hit), Clover List Payments, Clover List Refunds, Clover List Credits, Clover List Tax Rates, QuickBooks Create Sales Receipt, QuickBooks Create Refund Receipt.

Source patterns to match: https://www.commercesync.com/clover, https://synder.com/blog/how-to-sync-clover-pos-transactions-into-qbo/, https://quickbooks.intuit.com/app/apps/appdetails/clover/en-us/. Every field in this workflow is a known mapping — no LLM reasoning is required, keep it fully deterministic.