docs(accounting): merchant → Zoho Books transaction sync spec#354
docs(accounting): merchant → Zoho Books transaction sync spec#354OneTwo3D wants to merge 1 commit into
Conversation
…netwo3d-ims-lo2d) Engineering-ready plan to adopt Zoho Books as a first-class IMS accounting connector and mirror Revolut/Stripe/PayPal/eBay merchant transactions into Zoho at transaction granularity via per-provider/per-currency clearing accounts. Tracked as bd epic onetwo3d-ims-lo2d (12 child epics .1-.12). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4dbbeef61e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 2. Fetch/normalize provider transaction. | ||
| 3. Validate gross, fees, FX fees, net, settled currency, and state. | ||
| 4. Resolve IMS order and Zoho invoice. | ||
| 5. Post Zoho customer payment against the existing invoice. |
There was a problem hiding this comment.
Before this payment-posting flow is implemented, the spec needs to call out the existing paid-order path: WooCommerce imports set _registerPayment when date_paid_gmt is present (lib/connectors/woocommerce/sync/order-import.ts:782-785), and both current accounting processors turn that into an INVOICE_PAYMENT follow-up after invoice creation. If Zoho copies that connector foundation and merchant webhooks also post the same Stripe/PayPal/Revolut payment here, Woo-backed paid orders will be double-paid in Zoho; require suppressing or consuming that legacy follow-up for merchant-backed methods before live posting.
Useful? React with 👍 / 👎.
| Existing IMS order and accounting data should be used for invoice matching: | ||
|
|
||
| - `SalesOrder` remains the IMS source of truth for order state. | ||
| - Existing accounting invoice IDs on orders are used to apply payments in Zoho. |
There was a problem hiding this comment.
The existing SalesOrder.accountingInvoiceId is a single unscoped back-reference written by whichever active connector posted the invoice, while connector-scoped rows live separately in AccountingSyncLog. If the merchant matcher uses this field as a Zoho invoice ID during a Xero/QBO-to-Zoho cutover, previously synced orders can fail payment posting or be matched to the wrong accounting document; the plan should require connector-scoped invoice links or an explicit Zoho-ID backfill/validation before applying payments.
Useful? React with 👍 / 👎.
1 participant
What
Adds the engineering-ready spec for adopting Zoho Books as a first-class IMS accounting connector (alongside Xero/QuickBooks) and mirroring every merchant transaction (Revolut Merchant, Stripe, PayPal, eBay) into Zoho at transaction granularity via per-provider/per-currency clearing accounts.
Key constraints captured in the spec:
Tracking
Filed as bd epic
onetwo3d-ims-lo2dwith 12 child epics (.1–.12) mapping 1:1 to the spec's §4 epics: connector registration → API surface → outbox core → invoice matching → Revolut MVP → Stripe → PayPal → eBay → refunds/disputes → ops UI → security/cutover → e2e reconciliation hardening.Open decisions (spec §13) must be closed before coding their respective stages.
Scope
Docs only — no code change. This is the plan of record for the Zoho connector work.
🤖 Generated with Claude Code