Commerce accounting and inventory

Invoice, subscription and refund lifecycle

customer.upserted creates or synchronizes a connection-scoped customer using revisions. Permitted updates include billing name, contact details, address and tax identity. Unrelated/manual customers are never automatically merged.
invoice.created, order.created and subscription.renewed create invoices. invoice.updated/order.updated apply supported draft revisions. Stale revisions are ignored; conflicting revisions require review. Posted invoices are corrected by explicit credit events or governed Ledger adjustments, never overwritten.
Send a distinct source invoice ID for every monthly/yearly billing period. Send source-issued proration or plan-change invoices with actual charged amounts and the relevant period; MeshDex does not calculate subscription schedules or entitlements. Subscription created/changed/cancelled events update references with accountingEffect: NONE. Cancelling future renewal does not refund or void a paid period.
invoice.cancelled/order.cancelled void unpaid drafts and release unfulfilled reservations. Posted/paid or fulfilled records require explicit credit/refund or return workflows.
payment.captured includes invoiceId, paymentId, currency, amountMinor and optional paidAt. It records confirmed captured cash into the configured bank/clearing account. Authorized/failed payments are references only.
credit.issued includes invoiceId, creditId, currency, amountMinor, taxMinor, reason and optional creditedAt. It reduces revenue/receivable; it does not return cash.
refund.completed includes invoiceId, refundId, currency, amountMinor, taxMinor, reason and completedAt. It records a confirmed gateway refund and corresponding credit. Include creditId to reuse an already issued matching credit; one credit can be consumed by only one matching cash refund. Otherwise a separate credit is created. Repeated IDs cannot produce duplicate credits/refunds. Refund created/failed events are references only.
Multiple partial refunds are supported within recorded cash and remaining credit/tax bounds. Physical returns use return.received with orderId, returnId, lines and qualityApproved; financial refunds do not automatically return stock. Returns default to pending inspection; source quality approval is honored only after an administrator selects the trusted source approval policy.

Clearing, settlement fees and chargebacks

Configure captured receipts into a clearing asset account when a gateway later deposits net cash. settlement.completed identifies settlementId, source currency, settlementCurrency, grossMinor, netMinor, feeMinor, feeTaxMinor, bankAccountId, feeAccountId and completedAt. Supply entries as RECEIPT or REFUND with stable externalId and amountMinor. Each recorded capture/refund must match exactly and can belong to only one settlement. Missing captures wait for dependency; duplicate/conflicting batches require review.

Gross is receipts minus refunds. Net plus fees and fee tax equals gross converted into settlement currency. Cross-currency settlements also require settlementExchangeRate, settlementExchangeRateSource and settlementExchangeRateDate; this rate converts source currency to payout currency. exchangeRate converts payout currency to Ledger base currency. Fee tax requires an input-tax asset account (feeTaxAccountId) and source feeTaxReference. Settlement releases verified carrying amounts from clearing, posts net bank deposit, fees/tax and explicit FX differences.

chargeback.opened identifies chargebackId, paymentId, currency, amountMinor, reason and completedAt. It records disputed money in a configured chargeback receivable against affected clearing/bank cash, without voiding the customer invoice. chargeback.reversed includes chargebackId, currency and completedAt and records recovery of that same dispute; foreign-currency recovery supplies its actual cash rate/source/date. Cumulative chargebacks cannot exceed the captured payment. Already-settled payment correction/reversal requires settlement reconciliation; it cannot silently undo a settled receipt.

Catalog identity and stock ownership

Product and variant IDs are stable source identifiers; SKU/name are descriptive identity, not automatic match keys. GET /api/integrations/commerce/v1/catalog/ returns approved mappings; follow its nextCursor. Catalog product events retain source references without overwriting approved Ledger/Supply products or publishing stock.

Approve mappings in Manage → Catalog & events. Choose Ledger only, external fulfillment, Supply stock, or Supply review. Only Supply stock automatically reserves stock; Supply review requires operator review. Supply availability uses the approved warehouse, reservations, recalls, stock disposition and safety stock. GET /api/integrations/commerce/v1/availability/?productId=your-source-id&variantId=your-variant-id returns the configured availability band or exact quantity.

fulfillment.completed commits the full existing reservation once. Partial fulfillment or changed reserved order lines require inventory review. return.received cannot exceed fulfilled quantities and uses the approved return location. Supply-to-channel publication is for separately enabled managed adapters; Shopify/WooCommerce adapters are not claimed as available by this contract.

Sandbox, historical import and controlled matches

Use a separate Test connection first. It validates payload, setup, mappings and tax and records TEST_VALIDATED without posting live customers, invoices, receipts, credits or stock.
POST /api/integrations/commerce/v1/batches/ with events as a JSON array and dryRun: true validates a normal batch. Add historical: true to retain a historical preview with source invoice totals per currency, review items and an approval hash; it remains a preview even if dryRun: false is supplied.
In Manage → Reconciliation & imports, match any existing manual customers and invoices before applying. Enter exact external and Ledger IDs plus an audit reason. Invoice matching checks customer, currency and original total against a version 2 source snapshot. Customer billing synchronization requires a separate explicit checkbox.
Review source totals and every review item. Apply reviewed import requires authorized workspace administration, active Live connection, the exact preview hash and an audit reason. It queues up to 25 events per action; Resume import continues the checkpoint. Queue completion is not accounting completion.
Inspect retained event outcomes and reconciliation after processing. Repeated/resumed application reuses receipts. Fix missing dependencies/mappings before retrying. A changed source batch requires a new preview; never replace immutable payment/refund values.

Optional deferred service revenue

For a SaaS connection, an accountant may choose Defer over the service period and an approved deferred liability account in Accounting routing. Newly posted subscription invoices use their source billing/service dates. Existing invoices and approved schedules are not rewritten by a policy change.

Only net service revenue is deferred; tax and cash remain separate. Daily straight-line recognition uses UTC service dates and an exclusive end date. The last service day closes the rounding remainder. This policy supports one service obligation per source invoice.

Provide the subscription identity and explicit monthly/yearly billing service period with each source invoice. Confirm the approved revenue and deferred liability accounts before posting.
In Reconciliation & imports, open Deferred service revenue, select the source invoice and completed service date, then preview the earned and remaining deferred amounts.
Enter an approval reason and approve the exact preview. If your Ledger requires journal approvals, complete the required independent approvals before posting the prepared recognition journal.
Refresh after credits or invoice changes and review a new preview. A stale approval cannot overwrite the current schedule. Repeated requests recover their existing journal.

Credits reduce earned and unearned service revenue according to the original carrying value. Full credits close the schedule; unpaid invoice reversal uses the governed invoice workflow.
Do not edit or void recognition journals independently of their invoice. Credited invoice reversal requires accounting review.
Recognition is accountant initiated. It does not generate subscription renewal invoices, change access entitlements, or send gateway refunds.

Related guides

Need help with this workspace?

Ask your workspace administrator for access or contact support with the page name and a sanitized error message.

Invoice, subscription and refund lifecycle

customer.upserted creates or synchronizes a connection-scoped customer using revisions. Permitted updates include billing name, contact details, address and tax identity. Unrelated/manual customers are never automatically merged.

invoice.created, order.created and subscription.renewed create invoices. invoice.updated/order.updated apply supported draft revisions. Stale revisions are ignored; conflicting revisions require review. Posted invoices are corrected by explicit credit events or governed Ledger adjustments, never overwritten.

Send a distinct source invoice ID for every monthly/yearly billing period. Send source-issued proration or plan-change invoices with actual charged amounts and the relevant period; MeshDex does not calculate subscription schedules or entitlements. Subscription created/changed/cancelled events update references with accountingEffect: NONE. Cancelling future renewal does not refund or void a paid period.

invoice.cancelled/order.cancelled void unpaid drafts and release unfulfilled reservations. Posted/paid or fulfilled records require explicit credit/refund or return workflows.

payment.captured includes invoiceId, paymentId, currency, amountMinor and optional paidAt. It records confirmed captured cash into the configured bank/clearing account. Authorized/failed payments are references only.

credit.issued includes invoiceId, creditId, currency, amountMinor, taxMinor, reason and optional creditedAt. It reduces revenue/receivable; it does not return cash.

refund.completed includes invoiceId, refundId, currency, amountMinor, taxMinor, reason and completedAt. It records a confirmed gateway refund and corresponding credit. Include creditId to reuse an already issued matching credit; one credit can be consumed by only one matching cash refund. Otherwise a separate credit is created. Repeated IDs cannot produce duplicate credits/refunds. Refund created/failed events are references only.

Multiple partial refunds are supported within recorded cash and remaining credit/tax bounds. Physical returns use return.received with orderId, returnId, lines and qualityApproved; financial refunds do not automatically return stock. Returns default to pending inspection; source quality approval is honored only after an administrator selects the trusted source approval policy.

Clearing, settlement fees and chargebacks

Catalog identity and stock ownership

Sandbox, historical import and controlled matches

Use a separate Test connection first. It validates payload, setup, mappings and tax and records TEST_VALIDATED without posting live customers, invoices, receipts, credits or stock.

POST /api/integrations/commerce/v1/batches/ with events as a JSON array and dryRun: true validates a normal batch. Add historical: true to retain a historical preview with source invoice totals per currency, review items and an approval hash; it remains a preview even if dryRun: false is supplied.

In Manage → Reconciliation & imports, match any existing manual customers and invoices before applying. Enter exact external and Ledger IDs plus an audit reason. Invoice matching checks customer, currency and original total against a version 2 source snapshot. Customer billing synchronization requires a separate explicit checkbox.

Review source totals and every review item. Apply reviewed import requires authorized workspace administration, active Live connection, the exact preview hash and an audit reason. It queues up to 25 events per action; Resume import continues the checkpoint. Queue completion is not accounting completion.

Inspect retained event outcomes and reconciliation after processing. Repeated/resumed application reuses receipts. Fix missing dependencies/mappings before retrying. A changed source batch requires a new preview; never replace immutable payment/refund values.

Optional deferred service revenue

Provide the subscription identity and explicit monthly/yearly billing service period with each source invoice. Confirm the approved revenue and deferred liability accounts before posting.

In Reconciliation & imports, open Deferred service revenue, select the source invoice and completed service date, then preview the earned and remaining deferred amounts.

Enter an approval reason and approve the exact preview. If your Ledger requires journal approvals, complete the required independent approvals before posting the prepared recognition journal.

Refresh after credits or invoice changes and review a new preview. A stale approval cannot overwrite the current schedule. Repeated requests recover their existing journal.

Credits reduce earned and unearned service revenue according to the original carrying value. Full credits close the schedule; unpaid invoice reversal uses the governed invoice workflow.

Do not edit or void recognition journals independently of their invoice. Credited invoice reversal requires accounting review.

Recognition is accountant initiated. It does not generate subscription renewal invoices, change access entitlements, or send gateway refunds.