Skip to content

settlement-grossup-task-c , Handoff

URL: https://mkdocs.justinsforge.com/memory/handoffs/settlement-grossup-task-c-2026-06-10/

Date: 2026-06-10 Owner: the session that picks this up once Justin drops the exports Parent session: Fable 5 erpnext-finalize (A0 audit + daily posting engine session)

The Goal

Replace net-deposit revenue with TRUE gross accounting for every platform-settled sales channel in ERPNext: gross sales (43xx) + merchant/processing fees (5330) + shipping (5320) + collected sales tax (2315 liability), netting exactly to the bank deposits already in the books. This is the LAST data task gating the accountant package and the extended 2025 returns (it raises reported gross revenue AND adds deductible fees, and it is the only place the sales-tax liability gets populated). When this is done, the migration is finalized; only Justin's own book review + the accountant package remain.

Data Acquisition (verified 2026-06-10: Shopify is FULLY automated, no upload)

Shopify (NOVA + GOC): API, zero uploads. The existing per-brand tokens in ~/.forge-secrets/shopify-{nova,gusoutdoor}.env were LIVE-PROBED against shopify_payments/payouts.json and shopify_payments/balance/transactions.json, both return data (payout summary carries gross charges/fees/refunds; balance transactions carry per-order fee detail; the data layer's orders sync already has per-order total_tax + shipping). Pull programmatically via the _get/_paginate pattern in scripts/forge_datalayer_shopify_sync.py. Covers $25,652.84 (GOC) + $2,056.76 (NOVA) of 2025 net.

TikTok Shop (NOVA + GOC shops): manual export for the backfill. No Seller-API creds exist (the TikTok integration in forge is the Content Posting API, not Shop). Justin: Seller Center -> Finance -> Statements/Settlements -> export, each shop, 2025 + 2026 YTD. Biggest item: NOVA $42,374.52 net 2025; GOC $8,395.20. OPTIONAL follow-on: register a TikTok Shop Partner Center app (Finance API scope) for go-forward automation; approval takes days, do not block the backfill on it.

SweatPals (SIP): manual. No public API. Justin: payout/earnings statements showing gross ticket sales vs platform fee per payout, 2025 + 2026 YTD ($76,836.75 net 2025 across SP_SIPNSER + SWEATPALS labels).

Amazon (NOVA): small, manual. $652.92 deposited 2025 / $420.76 2026 YTD. SP-API exists (self-authorized Seller Central app, Finances API) but is overkill at this volume; Justin exports a Seller Central date-range report instead. Build SP-API only if the channel grows.

1099-Ks (see 1099K-RECONCILIATION-2026-06-10.md, computed from live API pulls): GOC gets a Shopify 1099-K (2025 gross $27,747.03, 704 txns, monthly table in the doc); NOVA does not (Shopify gross only $2,312.93). NOVA has a TikTok 1099-K (received); GOC does not (under $20k). PDFs are NOT API-retrievable (probed, 404). After gross-up, verify ERPNext per-channel gross >= each 1099-K Box 1a (IRS computer-matches these).

TikTok->Shopify order sync (live automation, mind the double-count): TikTok orders mirror into both Shopify stores (NOVA 1,157 TikTok-sourced 2025 orders vs 40 web). They do NOT settle through Shopify Payments, so payouts are clean, but NEVER treat mirrored orders as Shopify revenue (in the gross-up OR the forge data layer, whose Shopify orders sync ingests them). Use them for per-order tax/shipping enrichment + TikTok cross-checks.

Upload drop zone for the manual ones: /mnt/workspace/Forge/Finance Migration Summer 2026/Settlement Reports/ (one subfolder per platform; CSV preferred, PDF fine). Skip JWVR ($357.20 total, immaterial). Justin's full upload list: (1) TikTok settlement exports x2 shops, (2) SweatPals payout statements, (3) GOC Shopify 1099-K PDF (admin -> Settings -> Payments -> Documents), (4) NOVA TikTok 1099-K PDF (already in hand), (5) Amazon Seller Central date-range report for NOVA (optional, small). 1099-K PDFs go to Tax Returns/2025 Taxes/Intake/.

Current State

  • Books are LIVE: forge_erpnext_daily_post.py posts per-txn JEs twice daily; historical 2025+2026 fully posted; BS ties to bank/card statements to the penny; FY2025 closed.
  • All platform deposits are currently booked NET as revenue: 4320 (TikTok), 4310 (Shopify), 4370 (SweatPals). Per-entity net-deposit inventory and the posting design are in TASK-C-SETTLEMENT-GROSSUP-PREP-2026-06-10.md (workspace folder).
  • COA is ready: 2315 / 5320 / 5330 exist in all six companies (verified).
  • Blocked solely on the exports above.

Files You'll Work With

File Purpose
/mnt/workspace/Forge/Finance Migration Summer 2026/TASK-C-SETTLEMENT-GROSSUP-PREP-2026-06-10.md Net-deposit inventory + posting design (read first)
.../Settlement Reports/ Justin's export drop zone (TikTok + SweatPals only)
scripts/forge_datalayer_shopify_sync.py + forge_shopify_oauth.py Shopify API client pattern + per-brand env auth (payouts endpoints verified live)
scripts/forge_erpnext_daily_post.py Posting patterns to copy: pb.api(), post_je(), FINDB cheque_no idempotency keys
scripts/forge_erpnext_post_books.py api(), load_accounts() helpers (do NOT run its --apply)
scripts/forge_books_import.py Slice contract + income rules (4310/4320/4370 mapping)
.../AUDIT-INDEPENDENT-2026-06-10.md How the books were verified; replicate its tie-out style
~/.forge-secrets/erpnext.env API creds (bot key)

Likely Approach

  1. Shopify FIRST (unblocked today, no waiting on Justin): pull payouts + balance transactions via API for both stores, join order-level tax/shipping from the data layer, and post the Shopify gross-up end-to-end. This proves the JE pattern before the manual platforms arrive.
  2. Parse the TikTok/SweatPals exports into per-payout rows: gross sales, fees, shipping, sales tax collected, net payout, payout date. (PDFs: render with pymupdf in .venv-finance, then read; TikTok CSVs are clean.)
  3. Reconcile payouts to the bank deposits in finance.db (amount + date window). Expect near-perfect matching; investigate anything unmatched > $50 before posting.
  4. Build ONE summary gross-up JE per (entity, platform, month): Dr the revenue account for the booked NET amount (reversing it), then Cr gross sales, Dr 5330 fees, Dr 5320 shipping, Cr 2315 sales tax collected; entry nets to zero against the bank (cash does not move). Key each JE cheque_no=FINDB-GROSSUP-<entity>-<platform>-<YYYY-MM> so re-runs are idempotent and verify-able.
  5. Dry-run printing per-month tie-outs (net booked == net per reports) before --apply.
  6. Sales-tax sanity pass: TikTok Shop and (usually) SweatPals are marketplace facilitators that remit sales tax themselves, so 2315 may stay near $0 for them; Shopify (GOC's own store) is NOT, so GOC's 2315 balance is a REAL liability. Flag the GOC number to Justin explicitly (possible unfiled TX sales tax).
  7. Update the 2025 tax estimate working sheet if gross-up changes the K-1 picture (P&L net should NOT change materially; fees offset the revenue increase).

Don't Do

  • Don't run forge_erpnext_post_books.py --apply (retired, not idempotent, double-posts).
  • Don't touch the daily engine's seam/state db; gross-up JEs are separate, keyed FINDB-GROSSUP-*, and verify already ignores non-txn FINDB keys only for SEAM/SWEEP, so extend its skip-prefix list to include GROSSUP before posting.
  • Don't build the accountant package or touch accountant-pending items (garage QIP, reasonable comp); Justin reviews the books first.
  • Don't change finance.db (read-only; schema owned by the finances session, see data/finance/COORDINATION.md).
  • Don't reclassify the underlying bank-deposit txns; the gross-up layer sits on top.

Deliverables

  1. Parser + poster script scripts/forge_erpnext_settlement_grossup.py (dry-run default, --apply, idempotent keys), registered in MEMORY.md + topic file.
  2. Posted gross-up JEs for 2025 + 2026 YTD, all entities/platforms with reports.
  3. Tie-out worksheet SETTLEMENT-GROSSUP-TIEOUT-<date>.md in the workspace folder: per entity/platform/month, gross / fees / shipping / tax / net vs bank.
  4. GOC sales-tax liability flag to Justin (amount + period) if 2315 > 0.
  5. Go-forward note: monthly gross-up cadence (manual or /followup) until a per-payout feed exists.

Done When

  • Every uploaded report parsed; unmatched payouts vs bank deposits explained
  • Gross-up JEs posted + submitted; each month's entry nets to $0 cash effect
  • Per-entity revenue in ERPNext == platform-reported GROSS for covered channels
  • P&L net per entity changed only by genuine new info (document any delta vs the audited numbers)
  • 2315 balances reviewed; GOC flag delivered if nonzero
  • forge_erpnext_daily_post.py verify still all green
  • Tie-out worksheet written; MEMORY.md + topic file registered; handoff updated