MetaCompliance: Maxio → Upflow PDF integration

About this document

This document describes the production system delivered to bring invoice and credit note PDFs from Maxio (SaaSOptics) into Upflow, across MetaCompliance's four legal entities.

It is written for whoever takes the system over next, including someone who has never seen it before. Understanding it, running it, fixing it and extending it should be possible from this document alone, with no side explanation from anyone who worked on it earlier. Where a fact is unverified or unmeasured, it is labelled as such rather than smoothed over.

Each section starts with a plain-language summary. Technical detail follows in the same section, clearly separated.

Anyone about to change something starts at section 9. Sections 1 to 8 describe what the system is and how it behaves. Section 9 is how to touch it: the rules the work follows, the verification gates a change has to pass before it reaches production, and the full procedure for adding a new organization.

Table of contents

1. Executive summary
2. What the system does
3. System architecture at a glance
   • One architecture everywhere: the chunked pull
4. The three workflow families
   • 4.1 Sync workflows: the main job
   • 4.2 Cache builders: the prep work
   • 4.3 Monitoring workflows: observe and alert
   • 4.4 Anatomy of a sync workflow
5. Reliability by design
   • 5.1 Idempotent uploads
   • 5.2 Write-Ahead Log (WAL)
   • 5.3 Stateless across runs
   • 5.4 Multi-org isolation
   • 5.5 Failure classification
   • 5.6 Permanent vs transient failure handling
   • 5.7 Test Mode protection
   • 5.8 What happens if a run crashes
   • 5.9 Expiring Maxio links, and the redirect that hides the PDF
6. Operating the system day to day
   • 6.1 Where to look, and how to diagnose one invoice with no PDF
   • 6.2 Healthy steady-state signature
   • 6.3 When to escalate
   • 6.4 What the monitoring does not see
7. Known limitations and roadmap
   • 7.1 Denmark: currently gated
   • 7.2 Three categories of untreated invoices
   • 7.3 Hosting: the execution allowance is the near-term constraint, and the decision is open
   • 7.4 Go-live checklist
   • 7.5 An amended PDF is re-pushed automatically, within stated limits
   • 7.6 Open items
8. Reference appendix
   • 8.1 Workflow registry
   • 8.2 Data tables
   • 8.3 Credentials
   • 8.4 Schedule reference (Table 1 scheduled, Table 2 called only, Table 3 switched off)
   • 8.5 Per-organization reference formats
   • 8.6 Configuration reference
   • 8.7 Status values and error codes
   • 8.8 The Upflow API
   • 8.9 The Maxio (SaaSOptics) API
9. Making changes safely
   • 9.1 The change discipline
   • 9.2 The verification gates (G1 to G14)
   • 9.3 Adding a new organization

1. Executive summary

The system bridges a gap in MetaCompliance's invoicing stack: invoices and customers arrive in Upflow through the native Sage Intacct → Upflow sync, but the invoice PDF files are generated by Maxio (SaaSOptics) and do not flow natively to Upflow. This integration ferries every relevant PDF from Maxio to its matching invoice in Upflow, automatically.

Key facts:

2. What the system does

In one paragraph:

Business outcome

• MetaCompliance customers receive PDF-attached invoices in Upflow without any manual export-import work.
• Dunning campaigns in Upflow carry the underlying invoice as a downloadable attachment, for every invoice the sync has covered. Section 6.4 explains how to tell whether coverage is real rather than assumed.
• Finance team retains a complete audit trail of every PDF push (who, when, status, error if any). One class of invoice never reaches that trail, and section 6.4 says which.

What the system does NOT do

To prevent any ambiguity, the system explicitly does not:

• Create customers or invoices in Upflow. Those arrive via MC's existing Sage Intacct → Upflow sync.
• Modify any invoice data, billing logic, or subscription state in Maxio or Upflow.
• Generate or transform PDFs. It only ferries them as-is.
• Send any customer-facing communication. Upflow's own dunning engine handles that.

3. System architecture at a glance

Three layers, three jobs:

1. Cache builders prepare the data. They keep a fresh local index of Maxio invoice metadata, so the main workflow does not have to call Maxio repeatedly.
2. Sync workflows do the work. They pull unpaid invoices from Upflow, match them against the cache, fetch the PDF, validate it, and upload it to Upflow.
3. Monitoring workflows observe and alert. They post operational summaries to Slack and aggregate failures for weekly review.

All three layers run independently on schedules. They share state through n8n data tables (think of them as small SQL tables built into n8n).

One architecture everywhere: the chunked pull

In plain language. Upflow has no way to ask "give me only the unpaid invoices", so the sync has to read the whole invoice history of the org and sort it out itself. The original design read that history inside one single workflow run. For the largest org, that single run was measured at around 37 MB on an instance published with 320 MiB of RAM, and it was killed. What that establishes is not a documented limit per run, it is that a run of that size does not survive on this tier. The current design splits the reading into slices and hands each slice to a helper workflow, which throws away everything irrelevant before handing back a short list. The history is still read in full, it is simply never held in one place at one time.

Since 2026-08-20, every active sync on this instance uses the chunked design. The pull-all generation was retired in two waves that day, and the retired workflows are kept inactive as rollback references (section 8.1). The comparison below is the reason the migration happened, and it stays here because the rollback references still carry the old profile:

Which workflows use which: the six active syncs — three INVOICE, three credit note, across Limited, Ireland and DACH — are all chunked (v10.1). The only workflows still carrying the pull-all design are the two gated Denmark syncs, which are switched off and due to be rebuilt on the chunked pattern before Denmark is ever switched on (section 7.1).

4. The three workflow families

4.1 Sync workflows: the main job

What they do: for each org, every few hours, push the missing PDFs to Upflow.

How the unpaid list is built: the Upflow API does not expose a server-side filter for invoice state. The sync therefore reads the entire invoice list for the org (paginated, all states) and narrows it down to invoices whose state is DUE or OVERDUE. That narrowing happens inside the chunk sub-workflow, before anything returns to the parent (section 3). This is the input set of the filtering logic described further down.

Variants: two per org, eight in total.

Schedule: five cycles per day Mon-Fri. Inside each cycle the orgs are staggered, so no two syncs hit the same Upflow org at the same moment. The exact minute now differs per workflow and section 8.4 is the reference. The two Denmark syncs carry a schedule but are switched off (see section 7).

How a PDF is attached, and which identifier is used. This matters for anyone reading the workflow or reproducing a call by hand. The sync is driven by Upflow's own invoice listing, so every object it processes already carries both identifiers it needs, and there is no lookup call:

• customId is the invoice reference as MetaCompliance knows it. It is the key used to match the invoice against the Maxio cache.
• id is Upflow's own primary key, a UUID. It is what goes in the push URL.

The push itself is POST https://api.upflow.io/v1/invoices/{id}/pdf for invoices, and POST https://api.upflow.io/v1/credit_notes/{id}/pdf for credit notes.

Configuration knobs, identical on all six active syncs. They are set in Set: Sync config at the top of the workflow and are stored as text, not numbers, which is worth knowing before editing them. Since 2026-08-23 the two values that used to live buried in code — the re-check window and the reference-format rule — sit in the same node, and the code reads them fail-loud: a missing or unparseable value stops the run instead of silently compiling an empty rule.

Logic flow (simplified):

Filtering logic:

The sync does not push every unpaid invoice every time. It excludes:

• Invoices that have already been pushed successfully (tracked in mc-sync-log). Since 2026-08-23 this exclusion is no longer strictly permanent: when Maxio re-emails an amended version of an already-pushed invoice, the cache builders detect it and re-open exactly that invoice (section 7.5).
• Nothing is excluded for failing validation any more. A downloaded file that is not a PDF is logged, stays visible in mc-sync-failures, and is retried at every tick. The permanent exclusion that used to exist here was removed with the redirect fix (section 5.9); the 5 Limited invoices that had been frozen under it since 2026-05-17 were all recovered on 2026-08-20.
• Invoices whose Maxio record does not exist or has no PDF URL yet. These come back into the pool after 7 days and are re-checked weekly (section 5.6).
• Invoices whose reference does not match the Maxio numbering convention of that org. This rule is org-specific, and it has to be, because the orgs do not number their invoices the same way. Section 8.5 is the table of which rule each invoice sync carries, and section 6.4 explains what this exclusion costs in visibility.

These are the exclusions that decide whether a given invoice gets a PDF. The filter node applies five tests in all, including two that separate invoices from credit notes; section 4.4 lists them in the order they are tested.

This filtering means each run does the minimum work necessary. A steady-state run takes seconds on the smaller orgs; Limited was measured at around 65 seconds, because it always reads the full history through its sub-workflow before concluding there is nothing to do.

4.2 Cache builders: the prep work

What they do: keep a local index of all Maxio invoices for each org, refreshed every few hours.

Why this matters: Maxio's API is slow and rate-limited. Without a cache, the sync would have to query Maxio individually for every Upflow invoice, every run. The cache turns hundreds of API calls into a single lookup against an in-memory data table.

Variants: one per org, four in total.

Schedule: five runs per day, at :45, ahead of the syncs that read them. That is 15 minutes before the syncs that run on the hour (Ireland and DACH invoices), 30 minutes before the credit note syncs at :15, and 45 minutes before Limited's invoice sync at :30. The ordering is deliberate: the cache is always refreshed before anything reads it.

All four cache builders are active, Denmark included. The Denmark cache has been refreshing five times a day throughout, even though the two Denmark syncs are switched off. The practical effect is that the Denmark cache is warm and no cache work is pending on the day MC decides to switch that org on (section 7.1).

Logic flow:

Incremental design: the cache builder only pulls what has changed since the last refresh. Most runs process zero new records. This keeps the system fast and well under Maxio's rate limits.

Since 2026-08-23 the builders carry a second job: amendment detection. Each refreshed Maxio record now also stores two timestamps in the cache, last_emailed and auditentry_modified. For every record it refreshes, the builder looks up the sync log, and when the fresh last_emailed is newer than the one recorded at push time, it re-opens that invoice by flipping its log row to amended_repush_pending — section 7.5 is the full mechanism, including the guard that keeps pre-existing history from re-opening en masse. The flip is verified by re-reading the row, and a flip that cannot be verified stops the run before the watermark advances, so a detection is never silently lost.

Cache freshness: at the moment a sync reads the cache, it is between 15 and 45 minutes old, depending on which sync it is. That range covers the six active syncs; the two gated Denmark syncs sit outside it as their schedules currently stand, and section 7.1 covers what to do about that before switching Denmark on. Between two cycles the cache can be up to three hours old, which does not matter because nothing reads it in that window. The Maxio URLs used to download PDFs carry tokens that Maxio rotates, so the cache also keeps the freshest URLs available. Section 5.9 covers what happens when a token rotates anyway.

4.3 Monitoring workflows: observe and alert

What they do: track what the sync workflows did, classify any failure, and surface only what needs human attention.

This is intentionally a separate layer from the sync workflows themselves. The syncs focus on doing the work; the monitoring layer focuses on telling you about it. The monitoring sub-workflows are wired so that a failure inside one of them does not break the sync that called it. The reverse does not hold in the same way: most of the monitoring only runs when a sync calls it, so a sync that stops running takes its own reporting with it. Section 6.4 is the consequence of that asymmetry.

Four components

1. Independent liveness watchdog. MC - Heartbeat (added 2026-08-22) runs at 12:00 and 21:00 London on weekdays and checks the one thing the rest of the monitoring cannot: that every producer is still writing at all. It reads the age of the newest mc-sync-stats row for each of the six syncs and the newest mc-so-cache-progress row for each of the four cache builders. A sync writes one statistics row per tick even when it has nothing to do, so a stale timestamp means the workflow stopped running, not that it was idle. More than 7 hours without a write, an org missing from the table entirely, or a table that cannot be read at all: each posts a red alert to #n8n-alerts, and an inconclusive check is treated as red rather than as silence. Every Monday around noon it also posts one green proof-of-life message whether or not anything is wrong, so that the watchdog's own death is visible: if the Monday green stops arriving, the watchdog itself is down. Its one structural limit is that it runs on the n8n instance it watches, so it catches a silently disabled workflow — the failure that actually happened here — but not the whole instance going down. The Monday green is what bounds that residual case.

2. Operational Slack notifier. At the end of every sync run, a dedicated sub-workflow (MC - Slack notify risks) computes summary statistics and decides whether to post a message:

• Compares the current run against the previous run for the same org and entity type.
• Detects meaningful changes: new failure categories, error spikes, completion of catch-up phases.
• Posts to #metacompliance-n8n-sync only when something is worth attention.
• Since 2026-08-23, the delta-based thresholds are suspended on runs whose candidate batch is saturated (candidates_count >= batchCap): a full batch measures the batch refilling, not a business change. The critical threshold — a failed push — is evaluated on every run, unconditionally.
• Silent runs are intentional. Silence means no threshold was crossed on a run that reported. It does not mean a run happened; that question belongs to the heartbeat above.

3. Failure deduplication, and self-clearing. Every failed push triggers a sub-workflow (MC - Upsert failure to mc-sync-failures) that upserts a row into a deduplicated catalog:

• Composite key: invoice_id + org. The same failing invoice retried multiple times produces one row updated, not N rows.
• Stores last failure code, last attempt date, retry count.
• Used as the source of truth for "what currently needs attention", and as the input for the weekly recap.

A second sub-workflow (MC - Clear resolved failure from mc-sync-failures) does the opposite: when an invoice that had failed is later pushed successfully, its row is deleted. It is wired on all six syncs and on the manual re-push tool. mc-sync-failures is therefore a list of what is currently unresolved, not a history of everything that ever failed. An invoice that fixed itself leaves no trace there, and mc-sync-log is where its history lives.

4. Weekly recap. Every Monday at 08:00 London (09:00 France time), the scheduled workflow MC - Weekly failures recap:

• Reads mc-sync-failures for the past seven days, and mc-sync-stats for each sync's last recorded run.
• Groups failures by category (error_code) and by org.
• Posts a structured Slack message in #metacompliance-n8n-sync.

Since version 1.1.0 (2026-08-22) the recap verifies sync activity instead of assuming it, and it uses three output shapes:

• Stopped-sync alert (:red_circle:) when any sync recorded no activity at all during the window, or when the statistics table cannot be read. An empty failure list produced by a stopped sync used to read as good news; it no longer can.
• All-clear (:large_green_circle:) only when nothing was skipped and all six syncs ran during the window. The old wording that claimed "the sync system processed all eligible invoices successfully" on an empty failure list is gone: it asserted something the workflow never measured.
• Info digest (:bar_chart:) when invoices were skipped. Includes a breakdown by org, a detail per category with up to 5 sample customIds, and an action item: "no action required by default. If any listed invoice should be processed by the sync, please ping the integration owner with the customId."

Every message, whatever its shape, now ends with a Sync activity section giving the last recorded run per org — so an org with nothing to report is never simply absent from the message, because absence is exactly what a dead org used to look like.

The action item is deliberately framed around intent (should-it-be-in-scope), not around technical errors, because the skipped invoices are by design (see section 7.2 catalog A/B/C).

Severity levels and Slack behaviour

What to do when you receive an alert

The alert tells you which category of failure occurred. From there:

1. Open the n8n UI, navigate to Data Tables, select mc-sync-failures.
2. Filter by org and error_code matching the alert.
3. Each row carries a workflow_execution_id linking back to mc-sync-log for the full attempt history.
4. If the failure category is one of the three documented in section 7.2 (untreated cases), no action is required from MetaCompliance, these are awaiting product-team validation.
5. If the category is new, or growing, or unexpected: forward the Slack message to the integration owner.

Centralised exception capture: the MC Error Handler

A dedicated workflow, MC - Error Handler, was built specifically for this delivery to catch any runtime exception that escapes a workflow's own error branches. n8n provides the underlying errorWorkflow hook (the plumbing); everything that decides what to capture, how to format it, and where to post it is custom.

Coverage, verified on 2026-08-23. Every one of the 22 active workflows except the error handler itself names MC - Error Handler as its errorWorkflow. The handler is the expected exception, since it cannot be its own safety net.

How a sub-workflow failure propagates is no longer an open question: it was measured on this instance by a controlled test on 2026-08-23. A throwaway parent and sub-workflow were made to fail on a real scheduled tick, and n8n raised two independent error events: the sub-workflow's errorWorkflow fired carrying the root cause — the failing node and its message — and the parent's fired carrying only a generic wrapper error (Error executing workflow with item at index 0). The practical consequence is one rule: keep settings.errorWorkflow set on every workflow, sub-workflows included. Remove it from a sub-workflow and the only alert left is the parent's generic one, which names neither the node nor the reason.

When a covered workflow throws an uncaught exception, the handler fires automatically and posts a structured message to Slack channel #n8n-alerts. The post includes:

• Stack trace (truncated to 2500 characters)
• Failing node name and type
• Workflow name and id
• Execution URL (clickable, opens directly in the n8n UI)
• Execution mode (production / manual / retry)
• Retry info if applicable
• ISO timestamp

#n8n-alerts is intentionally separate from #metacompliance-n8n-sync so business signals (recap, info, warning) and technical exceptions never collide. Subscribers to #n8n-alerts see only events that need a developer's eyes; subscribers to #metacompliance-n8n-sync see only events that need an operator's eyes.

4.4 Anatomy of a sync workflow

In plain language. Opening a sync for the first time is intimidating: there are around sixty boxes on the canvas. Roughly four in ten of them are sticky notes, the yellow panels that document the flow and execute nothing, so the part that actually runs is closer to thirty-five nodes. Those nodes group into fourteen stages that execute in a fixed order, front to back, with one loop in the middle that walks the candidate invoices one at a time. This section is the map of those stages. Read it beside an open editor and the canvas resolves into a line.

Node counts, read from the workflow definitions on 2026-08-23:

Three n8n terms are used below, because each one decides behaviour and each is easy to change by accident in the editor:

• onError is a per-node setting that says what happens when that node throws. The default, stopWorkflow, turns the whole run red. continueRegularOutput passes the failed item down the normal output anyway. continueErrorOutput sends it down a second output reserved for errors.
• alwaysOutputData is a per-node setting that makes a node emit one empty item when it would otherwise emit nothing at all. It is used here so that a lookup returning zero rows does not stop its branch dead.
• $('Node name') is n8n expression syntax for reading the output of another node by name. The name is matched as a literal string, which is what makes the rename hazard at the end of this section real.

The fourteen stages, in execution order

Stages A to N are identical across the six active syncs. Same node names, same wiring, same onError and alwaysOutputData settings, same log-row shape. A maintainer who has read one sync has read all six. (The two gated Denmark workflows still carry the retired generation and are rebuilt before use, section 7.1.)

The five exclusions applied in stage E, in the order they are tested, each one skipping to the next invoice:

1. The invoice state is not DUE or OVERDUE. Credit note syncs skip this test, because Upflow's credit notes carry no state field at all (section 8.8).
2. The reference matches the credit note pattern. Invoice syncs use this to exclude credit notes; credit note syncs invert it and require it.
3. The invoice is already logged with status = 'success'. Re-opened only by the amendment detector, which flips the row out of success when Maxio re-emails the invoice (section 7.5).
4. The invoice is logged with a cache-miss code less than recheckAfterDays (7) days ago.
5. The reference does not match the Maxio numbering convention of that org. This rule is per organization and section 8.5 is the table.

A sixth exclusion used to sit in this list: an invoice once flagged invalid_pdf_magic was frozen for life. It was removed family-wide with the redirect fix (section 5.9); a bad download now retries every tick and stays visible in mc-sync-failures.

If no candidate survives, stage E emits a single placeholder item so that stages L and M still fire. A run with nothing to do still produces statistics and still reports. That is why a COVERED verdict proves the run happened and proves nothing about work being done (section 6.4).

Stage C in detail, and the scan invariants

All six syncs read the list the same way: ask Upflow for a count, build a chunk plan (page size 500, 10 pages per chunk), call the sub-workflow once per chunk, aggregate. The aggregate throws if the number of chunks returned differs from the plan, or if fewer invoices came back than the count said there were while the list was not genuinely exhausted. A partial scan — the failure mode where pagination stops early and the unfetched invoices are simply never considered — cannot complete green. This guard used to exist on two syncs only; it has covered all six since the family alignment of 2026-08-20.

One nuance was added when the credit note syncs joined the pattern. On /credit_notes, Upflow's announced total can overstate what the API will actually deliver (a measured quirk, currently under investigation on Limited — section 7.6). The sub-workflow therefore treats a final short or empty page as the legitimate end of the list and reports it as listExhausted; the parent tolerates the shortfall only in that case, and counts it openly as phantomTotalDeficit in the run's verdict instead of hiding it. A non-empty page arriving after a short one is still a hole in the pagination, and still throws.

Inside the sub-workflow (three nodes, one per chunk call): When Executed by Another Workflow receives the chunk descriptor, HTTP: Upflow list invoice chunk fetches that chunk's pages, and Code: Filter outstanding + trim chunk verifies the pagination, keeps only the outstanding invoices, trims each one to four fields, and returns a single item. Its pagination checks throw rather than warn. The six sub-workflows are byte-identical in their code within their family; the only differences between them are the workflow name, the endpoint, and the Upflow credential attached to the HTTP node.

The redirect resolution runs on all six syncs. Between the write-ahead row and the download, HTTP: SaaSOptics resolve redirect probes the cached URL without following redirects, and Code: Resolve final PDF URL rebuilds the address when the answer is a 302. Section 5.9 explains why. HTTP: SaaSOptics download PDF then reads its URL from that node instead of from the cache node.

Settings that look cosmetic and are not

Each of these is one click away from being changed and none of them announces what it costs.

One asymmetry is worth knowing because it is consistent across all six active syncs rather than being drift: the call that clears a resolved failure row carries onError: continueRegularOutput, so a cleanup problem never breaks a tick whose push already succeeded. The call that records a failure carries no such protection, so if it errors, the run goes red and the remaining candidates in the batch are abandoned. Whether that asymmetry is intentional cannot be established from the workflow definitions.

The rename hazard

This is the shortest way to break a sync, and it produces no warning at edit time. When one node reads another's output through $('Node name'), the name is a literal string. Renaming the target leaves the editor perfectly happy, saves without complaint, and fails at runtime on the next scheduled tick.

The nodes below are referenced by name somewhere in their workflow. Do not rename any of them. If one must be renamed, every expression pointing at it has to be found and updated in the same edit.

Set: Sync config is the one to be most careful with. Renaming it breaks the workflow everywhere at once, and the failure will look like a configuration problem rather than a rename.

5. Reliability by design

The system has been engineered so that a failed, crashed or half-finished run never loses a PDF, never duplicates one, and never leaves state that has to be cleaned up by hand. That property has held in production. It is a different property from "the system keeps running", which section 5.8 addresses separately.

Each mechanism below is explained with the failure it protects against.

5.1 Idempotent uploads

What it means: uploading the same PDF twice has the same effect as uploading it once. Upflow's PDF endpoint is overwrite-on-write. The second push replaces the first, byte-for-byte identical, no duplicate.

What it protects against: any case where the system "thinks it might not have pushed" (network blip, log write failure, worker restart mid-push). The next run will simply re-push, and Upflow ends up in the correct state.

5.2 Write-Ahead Log (WAL)

What it means: before any PDF push, the system writes a row in mc-sync-log with status attempted. The actual push happens next. After the push, the outcome is written as a second row, not as an update to the first: mc-sync-log is append-only (section 8.2), so a completed attempt leaves two rows, the attempted marker and the outcome. Both carry the same workflow_execution_id, which is what pairs them.

Since 2026-08-23 the outcome row also records so_last_emailed, the Maxio re-email timestamp at push time — the baseline the amendment detector compares against (section 7.5).

What it protects against: a crash between the moment the PDF goes out and the moment that fact is recorded. Even if the crash happens mid-push, there is always a trace of the attempt in the log table. The next run will see the attempted-but-not-success row and re-process it.

5.3 Stateless across runs

What it means: each sync run starts from scratch. It does not rely on "where the last run stopped". It re-reads the org's whole invoice list from Upflow, narrows it to the unpaid ones on its own side because Upflow offers no server-side state filter (section 4.1), then checks the log to skip already-pushed ones.

What it protects against: any failure that leaves the system in an unclear state. There is no "pointer to restart from" that could be corrupted, lost, or out of sync. The truth is always: read Upflow, read the log, compute the delta.

5.4 Multi-org isolation

What it means: each of the four MetaCompliance entities has its own dedicated workflows, credentials, cache tables, and log entries. A failure or anomaly on one org does not propagate to the others.

What it protects against: any per-org problem (credential rotation, Maxio rate limit on one entity, schema oddity) cannot cascade. The Limited team's bad day does not affect the Ireland team.

Where the isolation stops. It is logical, not physical. All four orgs run on the same n8n instance, so they share its memory and its monthly execution allowance. An org that runs heavy or crash-loops consumes both at the expense of the others, which is the subject of section 7.3.

5.5 Failure classification

What it means: every failed push is logged with a specific error_code. Codes include things like no_so_match_in_cache, no_einvoicing_url, invalid_pdf_magic_*, js_exception_encode, and HTTP error codes for push failures.

What it protects against: "something failed and nobody knows why". With classified failures, the weekly recap can tell you "10 invoices failed for reason X (action: ask MC to refresh Maxio), 2 invoices failed for reason Y (action: investigate)". Every failure becomes actionable.

5.6 Permanent vs transient failure handling

The system distinguishes failures it should retry from failures it should stop retrying.

The in-run retry, and what it does not cover. The two GET requests each sync makes, the Upflow invoice listing call and the Maxio PDF download, retry automatically 3 times at 5-second intervals. Stated plainly: this absorbs roughly 10 to 15 seconds of instability, and nothing more. A two-minute outage at either provider still fails the tick. The real safety net for anything longer is the next tick, which re-reads everything and picks up what was missed. That is by design, and it is why the idempotence described in section 5.1 matters more than the retry count.

Why the split matters: a naive retry-everything design would burn resources re-attempting hopeless cases. A naive give-up design would silently drop failures that would have healed on their own. The 7-day re-check is the compromise: bounded effort, no permanent give-up on anything that Maxio might populate later.

5.7 Test Mode protection

What it means: the system pushes PDFs even when an Upflow organization is in Test Mode. Test Mode blocks customer-facing communication (no dunning emails, no payment reminders), but does not block API data ingestion. This was validated empirically during build.

What it protects against: accidentally driving customer-facing activity before MC is ready. While an org is in Test Mode, customers see nothing, even though PDFs are accumulating correctly behind the scenes. When that org goes live, every invoice the sync has covered already has its PDF attached.

Where each organization stands, as of 2026-08-23:

5.8 What happens if a run crashes

A single crashed run costs nothing. Repeated crashes do.

A single crash. The run is marked crashed in n8n's execution log, the next scheduled run re-reads Upflow, re-checks the log and processes whatever still needs processing. No PDF is lost, none is duplicated, no cleanup is required. The only side effect is a missing statistics row in mc-sync-stats for that tick, which is cosmetic.

Repeated crashes. When a workflow crashes repeatedly, n8n stops scheduling it and sets it to inactive. That is not recovery, it is a silent outage: the workflow disappears from the running set, no exception is raised, no alert is posted, and the weekly digest keeps arriving as normal because it reports on failures rather than on absence.

What the chunked architecture changes, and what it does not. A pull-all run holds the org's entire invoice history in one execution. On the largest org that run was measured at around 37 MB, on an instance published with 320 MiB of RAM, and it crashed. The plan does not define a memory ceiling per execution; what is established is that a run of that size does not survive on this tier. The chunked architecture (section 3) has removed that exposure on all six active syncs since 2026-08-20; only the two gated Denmark workflows still carry the old profile, and they are rebuilt before use. The auto-disable behaviour itself is unchanged and is part of how n8n works. Any workflow that crashes repeatedly for any future reason will be switched off the same way, with the same silence.

How it is spotted. Since 2026-08-22 there are two automatic signals, and the manual check remains as the fallback:

1. MC - Heartbeat posts a red alert to #n8n-alerts within at most half a working day of a producer going quiet, and its Monday green proof-of-life bounds the failure of the watchdog itself (section 4.3).
2. The Monday recap turns red when a sync recorded no activity over the whole window (section 4.3).
3. The manual fallback: open the n8n workflow list and look at the Active toggle on each of the workflows listed in section 8.4, Table 1. All twelve should be active. Any workflow from that table showing as inactive, without someone having deliberately switched it off, is an outage in progress. Cross-check against the executions list: a workflow that stopped running leaves a gap, and the last execution before the gap is usually crashed.

If you find a sync switched off. Finding it is not by itself a reason to switch it straight back on.

• Establish why it stopped, before touching the toggle. A workflow that n8n disabled after repeated crashes will crash again if the cause is still there, and each attempt spends executions from the monthly allowance (section 7.3).
• Check which architecture that workflow carries. The memory exposure described above is addressed by the chunked architecture, but only on the two invoice syncs that use it. Section 4.1 describes the split and the registry in section 8.1 names them workflow by workflow. A sync still on the older architecture is still exposed to it.
• Repeatedly re-enabling a workflow that keeps being disabled is not a fix, and it burns allowance each time. Escalate instead (section 6.3).

5.9 Expiring Maxio links, and the redirect that hides the PDF

In plain language. The download links Maxio gives out contain a token that Maxio rotates. When a token has rotated, the old link no longer serves the PDF: it answers with a redirect to a different address. Following that redirect lands on Maxio's HTML viewer page, which is a web page, not a PDF. On a sync without the fix below, the system downloads that page, notices it is not a PDF, and records a failure.

What actually happens, measured. The redirect target drops the /invoice.pdf segment from the address. That single missing segment is the whole problem. On one invoice, following the redirect as-is returned 25 804 bytes of HTML. Re-applying /invoice.pdf to the redirect target returned a real PDF of 125 069 bytes.

The fix. Before downloading, the sync probes the URL without following redirects. If the answer is a 302, it reads the new location, re-applies /invoice.pdf, and downloads from there. It costs one extra HTTP request per invoice. Bundled with it: a file that genuinely is not a PDF is no longer excluded for life, so it is retried and stays visible instead of disappearing from the working set.

Where it is live: on all six active syncs, since the family alignment of 2026-08-20.

6. Operating the system day to day

6.1 Where to look, and how to diagnose one invoice with no PDF

Most questions have one right place to look, and looking in the wrong one gives an answer that is confidently wrong. The first row is the one that matters most.

One invoice shows no PDF in Upflow: the order to check it in

This is the most common question the system will be asked, and answering it out of order wastes time. Start with the invoice reference (its Upflow customId) and the organization it belongs to.

1. Is the sync for that organization still running at all? The Active toggle, checked against section 8.4 Table 1. A stopped sync explains every invoice at once and nothing below is worth doing until this is answered (section 5.8).
2. Does the reference pass that organization's format rule? Section 8.5 has the rule each sync carries and how to check a reference by eye. If it does not pass, the sync never treated the invoice as a candidate: there is nothing in any table to find, and section 7.2 is where that case belongs.
3. Look the reference up in mc-sync-log, filtering invoice_id on it. No row, with the format rule passing, means the invoice was never outstanding at a moment a sync ran: read its state in Upflow, since only DUE and OVERDUE are candidates (section 4.4).
4. A row with status = success means the PDF was pushed and Upflow accepted it. If the document in Upflow is not the current version of the invoice, section 7.5 is the reason: either the amendment has not been re-emailed yet (the detector's trigger), or the push predates 2026-08-23 and sits outside the detector's reach — the manual re-push tool covers both.
5. A row with status = failed carries an error_code. Section 8.7 says what produces each one and whether it clears itself. no_so_match_in_cache and no_einvoicing_url re-enter the pool on their own after 7 days; most of the rest are retried on every run.
6. A row stuck at attempted, with no outcome row from the same workflow_execution_id, means the run died part-way through that invoice (section 5.2). The next tick re-processes it.
7. The invoice is in mc-sync-failures only while it is still unresolved. An invoice that failed and later succeeded leaves no row there, so an empty result is not evidence that nothing ever went wrong (section 4.3).

6.2 Healthy steady-state signature

For each active org, a healthy day looks like:

• 5 INVOICE sync runs and 5 CM sync runs, all status: success in n8n executions list
• 4 cache builder workflows, each running 5 times, so 20 cache builder executions across the instance, all status: success
• Alongside every sync run, one or two sub-executions of its chunk sub-workflow (2 for Limited, 1 elsewhere at current volumes). These are normal and are described in section 3
• 2 heartbeat runs (12:00 and 21:00 London), silent except for the Monday-noon green proof-of-life
• Slack: zero or one operational message per day, severity none or info
• mc-sync-stats: one row per sync run, coverage_verdict starting with COVERED (steady state) or PARTIAL (catch-up in progress)
• mc-sync-log: continued append of new rows, all recent rows with status: success

The shared helper sub-workflows in section 8.4 Table 2 appear in the executions list as well, once per call, so the raw execution count on a healthy day is higher than the number of scheduled runs above.

Slack will surface most deviations from this, including — since 2026-08-22 — a sync that stopped running (heartbeat red, or a red Monday recap). What it still cannot surface is a run that completed green while a defective filter excluded everything. Section 6.4 covers that residual case.

6.3 When to escalate

The system is designed to operate autonomously. Reach out when:

• A failure category appears that is not documented (new error_code in mc-sync-failures).
• A heartbeat red lands in #n8n-alerts, or a Monday passes without the heartbeat's green proof-of-life. Either means a producer — or the watchdog itself — has stopped. Confirm with the Active-toggle check against section 8.4 Table 1.
• The Monday weekly recap is red, or fails to land in #metacompliance-n8n-sync at all. Since version 1.1.0 the recap checks sync activity itself, so a green recap now is a clearance for the week it covers; a missing one remains a signal about the recap itself.
• A message lands in #n8n-alerts (technical exception channel). These are rare and worth forwarding.
• Upflow or Maxio breaks backward compatibility on the APIs used (rare, but possible).
• You need to extend the system (new org, new entity type, new alert).

Escalate to the integration owner. That is a role, not a person: it belongs to whoever currently maintains this integration, and it moves when maintenance moves. The role is currently held at Upflow, at arthur.pomies@upflow.io. Confirm who holds it before escalating, and update this line when it changes hands. This is the route for anything in this list, and for any other question about the integration.

6.4 What the monitoring does not see

In plain language. The alerting in this system reports on things that went wrong. It does not report on things that did not happen. Those are different, and every blind spot below is an instance of the same gap. A green run and a COVERED verdict are not proof that work is happening. If you take one thing from this document, take that.

The blind spots — one closed on 2026-08-22, three still open:

The third blind spot has a mechanism, and it is worth stating as a live property of the system. Every invoice sync carries a rule that excludes references not matching the Maxio numbering convention of its own organization. The organizations do not number their Maxio invoices the same way, so the rule is per organization, and section 8.5 is the table of exactly which rule each sync carries today.

A rule calibrated for one organization and applied to another excludes that organization's entire normal traffic. Not a subset of it, all of it. And nothing in the system says so: the run stays green, the coverage verdict still reads COVERED - 0 eligible remaining, nothing is written to mc-sync-log, no failure row appears in mc-sync-failures, no Slack message is posted, and the Monday digest keeps arriving as an all-clear. The exclusion happens before the first log write, so the excluded invoices are not failures the system is being quiet about. They are candidates the system never had.

Nothing in the alerting can tell that state apart from an organization that has genuinely caught up. Where an organization is still in Test Mode, that setting is the only thing standing between the state and the customer: it accepts data while blocking outbound dunning, and it stops protecting anyone the moment that organization goes live (section 5.7).

As of 2026-08-23 that protection covers three organizations of the four. Ireland, DACH and Denmark are in Test Mode, so a filter defect on any of them stays inside Upflow and reaches no customer. Limited is live, so on Limited there is nothing in between. A rule that wrongly excluded Limited's traffic would produce the same green run, the same COVERED - 0 eligible remaining verdict and the same silence in Slack, and Upflow would go on dunning those customers with no invoice attached. Each organization's current mode is read in its own Upflow settings, not here.

What remains open. Denmark's two syncs carry the reference rule written for Limited, and section 8.5 flags them for it. Denmark's Maxio numbering has to be checked before that org is switched on, or the sync will exclude every invoice, run green, report COVERED, and push nothing, with no alert of any kind. This is the first item on the Denmark checklist in section 7.1.

The practical rule this leaves you with: when you want to know whether the system is working, do not ask whether anything failed. Ask whether anything was pushed. mc-sync-log growing over the last few days answers that question, COVERED does not.

7. Known limitations and roadmap

7.1 Denmark: currently gated

Status: infrastructure deployed identically to the other three orgs. Two workflows are off: the Denmark INVOICE sync and the Denmark CM sync, both tagged [GATED] in their names. The Denmark cache builder is active and has been refreshing the Denmark cache five times a day all along, so no cache catch-up is pending.

Reason: MetaCompliance does not currently bill the Denmark entity from Maxio. PDFs in Denmark Maxio are not relevant. MC plans to migrate Denmark billing to Maxio.

Before switching Denmark on, four things need doing. Each of the four below has a concrete failure attached to skipping it:

1. Check how Denmark numbers its Maxio invoices. The two Denmark syncs carry the reference-format rule written for Limited (YYYY-XXXXX), and section 8.5 states that rule alongside the one every other sync carries. If Denmark's numbering does not match it, the sync will exclude every invoice, run green, report COVERED, and push nothing, with no alert of any kind. Section 6.4 is the mechanism. This is the single highest-risk item on the list, because it fails invisibly.
2. Set the timezone on both Denmark workflows, and re-slot them. They are the only two scheduled workflows on the instance with no timezone declared. Left as they are, their three-slots-a-day schedule resolves against the instance default rather than Europe/London, so they may not fire at the times listed in section 8.4 Table 3. The slots themselves also need moving: the crons they carry, 10:00 and 10:15 and the same pattern at 13 and 16, fall 45 minutes before the :45 cache refresh of their own cycle rather than after it, so Denmark would read a cache last refreshed in the previous cycle, two and a half hours old at the credit note slot. That is not a breakage, it is a source of no_so_match_in_cache rows that would clear themselves a week later (section 8.7). Re-slot both syncs behind a cache refresh, using the clock view in section 8.4 and gate G9.
3. Check the execution quota first. Denmark adds executions to a plan allowance that is already substantially consumed. Section 7.3 has the measured numbers. Switching Denmark on without resolving the hosting question is how the instance runs out of executions mid-month.
4. Decide what Denmark's Upflow organization does at go-live. Same irreversibility as any other org, section 5.7.

Items 3 and 4 are checks. The other two carry work: item 2 always, since the timezone and the slots both have to be set, and item 1 only if Denmark turns out to number its Maxio invoices differently, in which case the reference rule has to be changed on both Denmark syncs. Do them in the order above, because item 1 decides whether there is anything to fix at all.

7.2 Three categories of untreated invoices

During backfill, three categories of unpaid invoices were observed in Upflow that the sync does not process. They require MC's product team to confirm intent:

Each category has been catalogued. MC's product team should validate whether these are expected to have PDFs (in which case a fix is needed) or expected to remain PDF-less (in which case the system is correct). The first category is worth checking with more care than the other two, because a wrongly excluded reference produces no signal anywhere.

7.3 Hosting: the execution allowance is the near-term constraint, and the decision is open

Memory is no longer the binding constraint. The chunked architecture (section 3) cuts the largest parent run from around 37 MB to under 2 MB, and it has covered all six active syncs since 2026-08-20. The next memory ceiling is a different one: the mc-sync-log read that every run performs grows with the table itself (section 7.6).

What binds now: execution volume. The Starter plan allows 2 500 executions per month:

Current recommendation: upgrade the n8n Cloud plan to Pro. It clears the execution ceiling, keeps the instance managed, and requires no migration, no re-deployment, and no change to any workflow.

Self-hosting stays on the table, but as an option rather than the default. It becomes the better answer if MC's scale changes substantially, or if MC decides it wants to own the infrastructure for reasons of its own. It carries an operational cost that the Cloud plan does not: patching, backups, uptime, and the alerting that goes with running a server. That cost is worth paying for a reason, not by default.

7.4 Go-live checklist

Going live flips an Upflow org from Test Mode to production. The next scheduler tick after the flip (default 08:30 org-time) will trigger automatic dunning actions on every eligible invoice. The decision is a MetaCompliance business decision, the click is a MetaCompliance admin action.

This procedure has been carried out once and is still ahead three times. As of 2026-08-23, Limited is live and Ireland, DACH and Denmark are still in Test Mode (section 5.7). What follows applies to each organization that has not gone live yet, one organization at a time.

Start by reading the org's current mode in Upflow. The date above is a snapshot and the state changes by an action inside Upflow, so check the target org's settings first and confirm it is actually still in Test Mode before working through the steps below.

Per-org checklist before clicking "Go live":

1. Confirm coverage is real, not just declared. Two checks, and the second is the one that counts:
   • Check the latest mc-sync-stats row for the org. coverage_verdict should start with COVERED, not PARTIAL. If PARTIAL, review what remains and whether it falls under section 7.2 (catalog A/B/C, expected) or something new (escalate).
   • Then check that mc-sync-log actually contains successful pushes for that org, over a period that makes sense. COVERED on its own is compatible with the sync having pushed nothing at all (section 6.4), so a verdict without a populated log is not evidence of coverage.
2. Spot-check 3 to 5 invoices in Upflow UI. Confirm the PDF is attached and downloadable, that it opens correctly, that the content matches the customer record.
3. Confirm internal alignment. Inside MetaCompliance: finance team aware of the date, dunning policy reviewed, customer service ready for inbound questions.
4. Pick a quiet day and an early time. A weekday morning (not Friday, not before a holiday) gives the most reaction window if anomalies appear.
5. Stagger across orgs. Where more than one organization is still in Test Mode, take them one at a time rather than together. Ireland is the smallest and the lowest blast radius, so it is the natural first, then DACH. Limited is already live and is out of that sequence. Observe 24 to 48 hours between them. Denmark stays gated until MC migrates its billing to Maxio.
6. Subscribe to both Slack channels. #metacompliance-n8n-sync (business signals) and #n8n-alerts (technical exceptions). Keep them in front of you for the first day post-go-live.
7. Click "Go live" in Upflow UI on the target org. The flip is irreversible.
8. Watch the next scheduler tick. The first automated dunning batch will fire at the next 08:30 org-time. Confirm volume and recipient list match expectations.
9. Reach out to the integration owner if anything looks off. Within the first 48 hours, treat any unfamiliar Slack message as worth a forward.

7.5 An amended PDF is re-pushed automatically, within stated limits

In plain language. Once an invoice's PDF has been pushed, the invoice is excluded from future runs, which is what keeps each run cheap. Until 2026-08-23 that exclusion was permanent: a PDF amended in Maxio after its push — a PO number added after the invoice was first sent, say — never reached Upflow, and nothing signalled that the two versions differed. That gap was demonstrated end-to-end on a live invoice. Since 2026-08-23 the system detects the common form of it and re-pushes on its own.

How detection works. The cache builders already refresh every Maxio record whose modification timestamp moved. They now also store the record's last_emailed timestamp in the cache, and every successful push records the same timestamp in its log row (so_last_emailed). When a builder refreshes a record whose fresh last_emailed is newer than the one recorded at push time, it flips that invoice's log row from success to amended_repush_pending. The invoice thereby leaves the already-pushed exclusion on its own, and the next sync tick re-pushes the current PDF and records a new baseline. Both sides of the comparison are Maxio's own timestamp — no mixed clocks. The flip is verified by re-reading the row; a flip that cannot be verified stops the builder before its watermark advances, so a detection cannot be silently lost.

Why the trigger is the re-email date and not the modification date. Measured on 2026-08-20 on a 40-invoice sample: Maxio's auditentry.modified moves in system-wide e-billing batches — 18 of the 40 invoices carried a modified inside the same 1.2 seconds. As a trigger it would have re-pushed 22.5 % of the sample, almost all of it batch noise. The re-email date isolated exactly the one invoice in the sample whose amendment was proven by reading both PDFs.

The limits, stated plainly:

• Pushes made before 2026-08-23 are out of the detector's reach. Their log rows carry no baseline, and the guard treats an empty baseline as "never flip" — deliberately, because without it the entire pushed history would have re-opened at once. Anything older goes through the manual tool below.
• An amendment that is never re-emailed is not detected. The re-email is the trigger. Same channel: the manual tool.
• Latency. The detector sees a re-emailed invoice when the cache builder next refreshes that record, which happens when Maxio's e-billing system next touches its modification timestamp: hours to a few days. The sync is idempotent, so late is safe.

The backstop: MC - Manual re-push by invoice number. An operator workflow, kept inactive and run by hand, that takes an organization and a list of invoice references, reads the live Maxio record, resolves the fresh PDF through the same redirect-and-validation chain as the syncs, and pushes it — deliberately ignoring the already-pushed exclusion, since bypassing it is its purpose. dryRun is on by default: the full chain runs and reports what it would push, without writing anything anywhere. Limited, Ireland and DACH invoices only; Denmark and credit-note references are refused loudly. Every real push it makes lands in mc-sync-log like any other, with its own marker.

7.6 Open items

Everything on this list is known and none of it is done as of 2026-08-23. It is here so that nobody rediscovers these the hard way.

As of 2026-08-23, Limited is the one organization out of Test Mode (section 5.7), so it is the one where Upflow dunning reaches real customers. The two Limited-specific items that stood here in the previous version — five invoices frozen under the old validation rule, and the redirect resolution being live on one org only — were both resolved on 2026-08-20.

8. Reference appendix

8.1 Workflow registry

Sync workflows (8 total: 6 active + 2 gated). All six active syncs are v10.1, chunked with redirect resolution (section 3). The two gated Denmark workflows still carry the retired v9 architecture and are rebuilt before use.

Chunk sub-workflows (6, active, no schedule of their own):

Cache builder workflows (4 total, all active, Denmark included):

Sub-workflows and utilities:

Deployed but switched off (11). Every retired workflow now carries a [DEPRECATED x.y.z], [GATED] or [PARKED] prefix — since 2026-08-23 none of them displays as a normal workflow:

What else is on the instance. The n8n interface reports 81 workflows in total, which is a larger number than anything above, so here is the reconciliation:

8.2 Data tables

8.3 Credentials

All credentials live in MC's n8n cloud instance under the credentials list. None are stored outside. Listed below by ID for traceability. Rotation is handled by MetaCompliance (Upflow and Maxio admin sides); updating the credentials in n8n after rotation falls to the integration owner.

8.4 Schedule reference

This reference is per workflow, exhaustively, and it includes the workflows that carry a schedule but are switched off.

Timezone, once, so it does not need repeating. Every active scheduled workflow declares Europe/London. London and Paris both follow the EU daylight-saving rule, and that rule switches both zones at the same instant (01:00 UTC, on the last Sunday of March and the last Sunday of October). Paris is therefore London + 1 hour, permanently, with no seasonal exception. A Paris reader never has to adjust for the time of year.

Cron format. n8n uses six fields: [Second] [Minute] [Hour] [Day-of-month] [Month] [Day-of-week]. So 0 45 7,10,13,16,19 * * 1-5 reads as "at second 0, minute 45, in hours 7, 10, 13, 16 and 19, on any day of any month, Monday to Friday".

The daily rhythm, in plain language

One cycle repeats five times a day, Monday to Friday. Nothing runs at weekends.

Each cycle spans from :45 to :30 of the following hour, and the order inside it follows the data dependency: the cache is always refreshed before anything reads it.

1. :45 the four cache builders refresh the Maxio index for all four orgs.
2. :00 the invoice syncs for Ireland and DACH run.
3. :15 the three credit note syncs run (Limited, Ireland, DACH).
4. :30 Limited's chunked invoice sync runs.

Cycles start at 07:45, 10:45, 13:45, 16:45 and 19:45 London (08:45, 11:45, 14:45, 17:45 and 20:45 Paris). On top of that: the heartbeat at 12:00 and 21:00 London — a few seconds each, inside otherwise free windows — and one weekly job, the failures digest on Monday morning.

The day by the clock, and where the free windows are

The three tables that follow this view are organised by workflow, and they are the exhaustive per-workflow reference. This view is the same schedule organised by time, and it answers a different question: is right now a safe moment to launch a workflow by hand or to deploy a change?

What the hosting plan actually says, since the answer rests on it. n8n publishes two figures for the Starter tier: five concurrent executions and 320 MiB of RAM, the RAM being a resource of the instance rather than an allowance held open for each execution separately (n8n pricing page and n8n Cloud subscription features per tier, both read 2026-08-20). Anything started beyond the concurrency limit is not rejected: n8n queues it and runs it in FIFO order once capacity frees up (n8n Cloud concurrency documentation, same date). So runs on this instance are not serialised, and up to five of them can be in flight together, drawing on the same published memory figure. What n8n does not document is whether one execution's memory is held apart from another's. The schedule in this section was laid out on the assumption that it is not, so a manual run started inside an occupied slot competes with the scheduled one for the instance allowance. That assumption has not been verified against the vendor, and the free windows below are what keeps the question from mattering.

How long a slot is treated as busy. Each slot below is drawn as occupied for 2 minutes. That is a safety margin, not a measured maximum: measured runs take 5 to 30 seconds, and the longest measured, Limited's chunked invoice sync, around 65 seconds. Every free window below is computed from the slot plus that 2-minute margin.

One weekday, 07:45 to 20:32 London, drawn to scale. One character is roughly 15 minutes:

Wide diagram: scroll it sideways.

07:45       10:45       13:45       16:45       19:45
███░░░░░░░░░███░░░░░░░░░███░░░░░░░░░███░░░░░░░░░███
 ↑             ↑
 │             └─ 133 min free, the long windows are the gaps BETWEEN cycles
 └─ one cycle: 4 slots packed into 47 min

███ cycle, 4 scheduled slots in 47 min      ░░░ free window, 133 min

The full clock, all 20 slots. London on the left, Paris beside it.

Wide diagram: scroll it sideways.

  LONDON  PARIS   SLOT  /  FREE WINDOW                          x = workflows firing
  ──────  ──────  ────────────────────────────────────────────────────────────────

                  ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒»  673 min free   20:32 (prev) → 07:45
  ── CYCLE 1 ─────────────────────────────────────────────────────────────────────
  07:45   08:45   █ CACHE    x4   Limited · Ireland · DACH · Denmark
                  ▒   13 min free   07:47 → 08:00
  08:00   09:00   █ INVOICE  x2   Ireland · DACH
                  █ DIGEST   x1   Weekly failures recap   ← MONDAYS ONLY
                  ▒   13 min free   08:02 → 08:15
  08:15   09:15   █ CREDIT   x3   Limited · Ireland · DACH
                  ▒   13 min free   08:17 → 08:30
  08:30   09:30   █ INVOICE  x1   Limited (chunked, ~65 s measured)
                  ▒▒▒▒▒▒▒▒▒▒  133 min free   08:32 → 10:45
  ── CYCLE 2 ─────────────────────────────────────────────────────────────────────
  10:45   11:45   █ CACHE    x4   Limited · Ireland · DACH · Denmark
                  ▒   13 min free   10:47 → 11:00
  11:00   12:00   █ INVOICE  x2   Ireland · DACH
                  ▒   13 min free   11:02 → 11:15
  11:15   12:15   █ CREDIT   x3   Limited · Ireland · DACH
                  ▒   13 min free   11:17 → 11:30
  11:30   12:30   █ INVOICE  x1   Limited (chunked)
                  ▒▒▒▒▒▒▒▒▒▒  133 min free   11:32 → 13:45
  ── CYCLE 3 ─────────────────────────────────────────────────────────────────────
  13:45   14:45   █ CACHE    x4   Limited · Ireland · DACH · Denmark
                  ▒   13 min free   13:47 → 14:00
  14:00   15:00   █ INVOICE  x2   Ireland · DACH
                  ▒   13 min free   14:02 → 14:15
  14:15   15:15   █ CREDIT   x3   Limited · Ireland · DACH
                  ▒   13 min free   14:17 → 14:30
  14:30   15:30   █ INVOICE  x1   Limited (chunked)
                  ▒▒▒▒▒▒▒▒▒▒  133 min free   14:32 → 16:45
  ── CYCLE 4 ─────────────────────────────────────────────────────────────────────
  16:45   17:45   █ CACHE    x4   Limited · Ireland · DACH · Denmark
                  ▒   13 min free   16:47 → 17:00
  17:00   18:00   █ INVOICE  x2   Ireland · DACH
                  ▒   13 min free   17:02 → 17:15
  17:15   18:15   █ CREDIT   x3   Limited · Ireland · DACH
                  ▒   13 min free   17:17 → 17:30
  17:30   18:30   █ INVOICE  x1   Limited (chunked)
                  ▒▒▒▒▒▒▒▒▒▒  133 min free   17:32 → 19:45
  ── CYCLE 5 ─────────────────────────────────────────────────────────────────────
  19:45   20:45   █ CACHE    x4   Limited · Ireland · DACH · Denmark
                  ▒   13 min free   19:47 → 20:00
  20:00   21:00   █ INVOICE  x2   Ireland · DACH
                  ▒   13 min free   20:02 → 20:15
  20:15   21:15   █ CREDIT   x3   Limited · Ireland · DACH
                  ▒   13 min free   20:17 → 20:30
  20:30   21:30   █ INVOICE  x1   Limited (chunked)   ← last slot of the day
                  ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒»  673 min free   20:32 → 07:45 next day

  Bar scale: 1 ▒ ≈ 13 min.  » = bar capped, the figure is the truth.
  Not drawn: the heartbeat at 12:00 and 21:00 — it reads two tables and finishes in
  seconds, so the free windows above remain usable as stated.

Three short gaps inside a cycle, four long ones between cycles. A cycle holds 4 slots, so it contains 3 internal gaps of 13 minutes each. The 4 windows of 133 minutes are the gaps between the five cycles, and the fifth long window is the overnight one.

The week. Monday to Friday are identical, one extra job aside. Weekends are empty. That is the whole weekly picture, so it does not need a grid:

Wide diagram: scroll it sideways.

       07:45       10:45       13:45       16:45       19:45
  Mon  ███░░░░░░░░░███░░░░░░░░░███░░░░░░░░░███░░░░░░░░░███   ★ + weekly digest 08:00
  Tue  ███░░░░░░░░░███░░░░░░░░░███░░░░░░░░░███░░░░░░░░░███
  Wed  ███░░░░░░░░░███░░░░░░░░░███░░░░░░░░░███░░░░░░░░░███
  Thu  ███░░░░░░░░░███░░░░░░░░░███░░░░░░░░░███░░░░░░░░░███
  Fri  ███░░░░░░░░░███░░░░░░░░░███░░░░░░░░░███░░░░░░░░░███
  Sat  ················ nothing scheduled ················
  Sun  ················ nothing scheduled ················

  ███ cycle (4 slots, 47 min)   ░░░ free (133 min)   ★ Monday-only job

Three facts carry the week:

1. Every weekday is the same shape. Five cycles, four 133-minute windows between them.
2. Monday 08:00 is the one exception. The weekly failures recap (0 0 8 * * 1) fires on top of the two invoice syncs already scheduled at 08:00, which makes it the busiest :00 slot of the week, three workflows on the same second. Not a good moment for a manual run.
3. Saturday and Sunday are completely free. No cron on this instance carries a weekend day in its day-of-week field. The window from Friday 20:32 to Monday 07:45 is 59 h 13 min, and it is the right place for anything long or risky.

The free windows, with their durations:

Wide table: scroll it sideways.

Rule of thumb. Between cycles there is just over two hours. Inside a cycle there are thirteen minutes. If it is not clear which of the two the moment falls in, it is not a free window.

Peak concurrency, counted as workflows firing on the same second:

On that ranking. The busiest instant of the week is not Monday 08:00. It is each :45 cache-builder slot, four workflows on the same second, five times a day. Monday 08:00 is the busiest :00 slot and the week's only asymmetry, which is a different claim and the accurate one.

The two Denmark syncs are absent from everything above, and their times carry a caveat. They are switched off, so they do not fire at all today. They are also the only two scheduled workflows on the instance with no timezone declared, so the 10:00 / 13:00 / 16:00 shown for them in Table 3 is where Denmark would land once a timezone is explicitly set, not where it would land as the workflows currently stand. Table 3 carries the same warning underneath it. If Denmark is switched on with Europe/London set, three of the four 133-minute windows split into 88 minutes, then 13, then 28. The 17:32 → 19:45 window is the only one left whole, before and after.

Table 1: running on a schedule (12 workflows)

Wide table: scroll it sideways.

On the Denmark cache builder. It runs on the full schedule while the two Denmark syncs are switched off, so it refreshes a cache that nothing currently reads. The effect is that the cache stays warm and Denmark has no catch-up to do on the day it is switched on.

Table 2: no schedule of their own (10 workflows)

These are active but cannot start themselves. They run only when something calls them, which is why they never appear in the schedule above.

Wide table: scroll it sideways.

Table 3: deployed but switched OFF (11 workflows)

Wide table: scroll it sideways.

8.5 Per-organization reference formats

In plain language. Before a sync goes looking for an invoice in Maxio, it checks whether the invoice reference even looks like a Maxio reference. What "looks like" means is not the same in every organization, because the organizations do not number their Maxio invoices the same way. Each sync therefore carries its own rule. This is the table of what each one carries. Section 6.4 is why getting one of them wrong is invisible.

The rules are built from three patterns. The notation on the left is the regular expression as written in the workflow; the right-hand column is the same thing in a form anyone can check a reference against by eye.

The rule in force, per sync (the two gated Denmark rows included):

Wide table: scroll it sideways.

Checking a reference by hand, without reading any code. Entirely ARADJ- and digits: skipped everywhere. Nothing but digits: skipped on Limited, Ireland and Denmark, processed on DACH. Ends in .CM. and digits: only the credit note syncs will touch it, and the invoice syncs will not. Anything else: handed to that org's Maxio cache for matching.

The credit note syncs need no org-specific rule and carry none. Requiring .CM. plus digits already excludes ARADJ- references and bare integers by construction. That is why this hazard can only ever affect the four invoice syncs.

Where the rule lives. Since 2026-08-23, on the three active invoice syncs the pattern is a visible value — nonSoPattern in Set: Sync config — read by both the filter and its statistics mirror, fail-loud: a missing or invalid value stops the run instead of silently compiling a rule that excludes everything. The old trap of the value being written twice in code, and the two copies drifting apart, no longer applies to the value; the mirrored logic remains, so a change to how the rule is applied still has to land in both Code: Filter & match chain and Code: Compute stats from filter inputs in the same edit.

The two gated Denmark syncs predate the hoist and still carry the pattern inside their code, twice each, with the inline-versus-named-constant inconsistency that used to affect the whole family. They are rebuilt on the current pattern before use (section 7.1), which retires that inconsistency with them.

On where the digit rule came from. A code comment on Limited and Ireland records its justification as pending, which means the origin of the "at most six digits" test was never established even by whoever wrote it. The rationale that supports it today, that Maxio numbering there is YYYY-XXXXX, was written afterwards. Whether it was checked against Limited's and Ireland's real data or inferred cannot be established from the workflows. Treat it as an assumption that has held in practice, not as a verified rule.

8.6 Configuration reference

In plain language. Almost everything adjustable in a sync sits in one node at the top of the workflow, called Set: Sync config. It holds a handful of variables and every other node reads them from there. This section is what each variable is, what it is set to on each sync, and what to know before touching it. Two things are worth reading before the tables: batchCap = 0 now means the same thing — a dry run — on every active sync, and a few tunable values still live in code rather than in that node, a list that shrank on 2026-08-23.

Everything in Set: Sync config is stored as text, including the values that are obviously numbers. That is why every consumer parses them before use, and why a value typed with a stray character still looks perfectly fine in the editor.

Values per sync, read on 2026-08-23 (the gated Denmark pair included for completeness):

Wide table: scroll it sideways.

What each one controls, and what to know before changing it:

Tunable constants that live in code, not in Set: Sync config. This is the part a maintainer will go looking for in the configuration node and will not find. It shrank on 2026-08-23: the re-check window and the reference rule moved into Set: Sync config.

Wide table: scroll it sideways.

8.7 Status values and error codes

In plain language. Every attempt the system makes on an invoice ends up as one row in mc-sync-log, and two fields on that row say what happened: status says whether it worked, and error_code says why it did not. Both are closed sets. This section is the complete list of what can appear in them. Section 6.3 makes an operational decision depend on whether a code is one you have seen before or a new one, so the value of this list is that it is complete.

Exhaustive as measured on 2026-08-23, against the definitions of the six active sync workflows, the cache builders and the manual re-push tool. Two rows carry a caveat on the word "exact", and they are marked.

status takes exactly four values.

invoice_type is closed in the same way: INVOICE on the invoice syncs, CM on the credit note syncs, hard-coded in the pre-attempt node and in all five log-row builders.

error_code, the complete list.

Read one column with care. Permanent and retryable are not properties declared anywhere in the workflows. No node classifies a code. The behaviour is emergent: it follows entirely from which exclusions Code: Filter & match chain builds when it decides what is a candidate. The column below states that emergent behaviour, not a setting anyone can find.

Wide table: scroll it sideways.

Four things to take from that table:

1. Three codes are families, not fixed strings. Rows 4, 5 and 6 embed observed data in the literal itself. Any tooling that matches on exact equality will miss them. The workflows themselves match on the prefix for row 4 and never match on rows 5 or 6 at all.
2. Rows 9 and 11 are closed in form and open in value. The literal is always an HTTP status turned into a string, so the shape is exhaustive; the set of statuses Upflow can return on a PDF push is not documented and cannot be established from here. That is the one place where "exhaustive" needs its qualifier.
3. Only four retry behaviours exist, and together they are the whole retry policy: permanent on success, permanent on a magic-bytes failure (seven syncs of eight), a 7-day window on the two cache codes, and retry-on-every-run for everything else. There is no back-off, no dead-letter state, and no attempt counter that grows. The attempt_count column in mc-sync-log is written as a literal 1 by every builder, so despite its name it is not a running total. The count that does increment lives on the mc-sync-failures row.
4. The taxonomy is uniform across the six active syncs, plus the manual_… family that only the operator tool emits. Since 2026-08-20 no code is treated differently by one sync than by another.

8.8 The Upflow API

In plain language. Upflow is where the PDFs go. The integration reads a list of invoices from it and posts a file back, and that is the whole of the contract. What follows is that contract as this integration uses it, plus the handful of places where the API does not behave the way its shape suggests. Several of the architectural choices described earlier in this document are forced by the limitations listed here rather than chosen.

Base URL. Production is https://api.upflow.io/v1. A separate sandbox exists at https://api.sandbox.upflow.io/v1, fully isolated: separate database, separate test payment keys, separate outbound email domain, and no data crossing between the two. Both are declared in the vendor's OpenAPI schema.

There is no public machine-readable copy of that schema. The vendor's developer portal is a JavaScript application that cannot be fetched, and the obvious schema URL answers 404. The only queryable endpoint reference is a copy obtained from the vendor and held locally, so whoever takes this over should ask the vendor for one rather than assume the statements below are still current. Everything said here about the schema was read from such a copy at the date on this document.

Authentication. Two headers, both mandatory on every request. Omitting either returns 401.

X-Api-Key:    <key>
X-Api-Secret: <secret>

Two properties of a key pair are worth knowing before anyone debugs one:

• Keys are issued per organization, in that organization's own settings. Four organizations mean four independent pairs, and there is no tenant selector on the request, so routing between them has to be explicit. This is why the integration carries four separate Upflow credentials (section 8.3).
• A pair is sealed to one environment. The same pair returns 401 against the sandbox host and works against production. A 401 on the sandbox host is therefore not evidence that a key is dead, it may simply be a production key. Probe both hosts before declaring a credential invalid, and never let a credential labelled sandbox hold a production key.
• There is no endpoint that says which organization a key belongs to. The only known way to attribute a pair is to fetch one customer and read the organization slug out of the URL field on the returned record. On an organization with no customers there is nothing to read, so the check comes back inert rather than failing.

Pagination.

Wide table: scroll it sideways.

If both page and offset are sent, offset wins. Response bodies carry the offset, page, limit and total alongside the array, whichever paging mode was used.

The four endpoints this integration calls. Nothing else is called against these organizations.

Creating or updating customers and invoices is deliberately never done from here. Those records belong to the ERP sync, and writing them from this integration would risk duplicating or overwriting data it does not own.

The identifier model, and the shortcut that does not work. This is the part most likely to be got wrong, because an Upflow invoice carries three identifiers and only one of them is the key this integration matches on.

Wide table: scroll it sideways.

The integration matches on customId. It is the one value that is identical in Maxio, in the ERP, and in Upflow. The push uses id. Both arrive together on the invoice listing, which is why the sync performs no lookup call at all (section 4.1).

What cannot be filtered server-side, and what that forces.

• There is no filter on invoice state. The complete filter set on the invoice listing is the three pagination parameters, two customer filters, an updatedAt comparison, customId, a dunning plan filter, and a sort order. There is no way to ask the server for the outstanding invoices only. Narrowing to outstanding has to happen after the pull, on the client side, which makes the read-everything-then-filter shape an incompressible baseline of the design rather than a choice. It is also the direct cause of the memory exposure described in sections 3 and 5.8.
• There is no field anywhere that says whether a PDF is attached. The schema carries no such flag on the invoice or on any sibling object, there is no attachments sub-resource for invoices, and the /pdf sub-path exposes a POST only, with nothing to read or probe with. The consequence for the design is direct: the integration has to keep its own record of what it has already pushed, which is what mc-sync-log is for.
• The field that looks like it answers that question does not. In production every invoice carries a populated PDF URL field regardless of whether a PDF was ever uploaded, and those URLs do not resolve. The vendor's own clarification is that the field means the record has a URL value, possibly a placeholder or a derived one, not that a PDF is stored and downloadable. The URL shape is identical in both cases, so there is no signal to tell them apart. The sandbox behaves differently, populating the field only after an upload, which means logic validated in sandbox produces a design that fails in production.
• customId filters invoices and is silently ignored on credit notes. The same parameter that returns a single match on the invoice listing is not a declared parameter on the credit note listing, so it is discarded and the whole pool comes back paginated. Code that assumes symmetry takes the first record of that pool and treats it as the match. Matching a credit note has to be done in memory.
• Credit notes carry no state field at all. Any outstanding-state test copied over from the invoice path evaluates against nothing and skips every credit note. That is why the four credit note syncs deliberately do not carry one (section 8.6).
• The documented state values are incomplete. The schema lists five. A full production scan found a sixth in live data, VOIDED. Write state tests as allow-lists over known-good values, and treat the schema's list as incomplete rather than closed.
• There are no webhooks. The vendor has answered this consistently for more than two years, most recently reconfirmed in January 2026. Polling is the official pattern, which is why this system is built on schedules.

Rate limits, and where the number actually comes from. The stated figures are 600 requests per minute and a cap of 10 simultaneous requests, with the vendor's own guidance for bulk work being to run sequentially, to cap at 5 concurrent if parallelising, and never to run simultaneous operations against entities linked to the same customer.

One non-obvious rejection. Requests carrying a default Python HTTP library User-Agent receive 403 from the production host even with entirely valid credentials, reproduced with the User-Agent as the only variable while the same headers pass from a normal command-line client. It is a web application firewall rule. Any script written against this API has to set its own User-Agent.

The PDF upload endpoint specifically.

• Path parameter: the UUID, for the reason given above.
• Two body formats are accepted, both validated. A regular file upload with a single file field, and a JSON body carrying the PDF base64-encoded. This integration uses the JSON form, because in a chain of HTTP steps each upstream call would otherwise overwrite the binary slot with its own response. Base64 inside a JSON field survives that. The cost is roughly a third more bytes on the wire.
• The only success answer is 204 with no body. It is the only response code the schema declares and the only one observed, which is why the workflows test for exactly 204 (section 8.6).
• Overwriting is last-write-wins, verified byte for byte. Pushing a first PDF onto an invoice with none returns 204 and downloads back identical. Pushing a different PDF onto the same invoice returns 204 and downloads back as the second file, with the first gone. This is what makes re-pushing safe, and it is the property section 5.1 rests on: the integration never has to check whether a PDF is already there.
• This endpoint is the only channel that surfaces a PDF in the interface for these organizations. A workspace-level setting restricts visible PDFs to those uploaded through it, and PDFs arriving by any other route are hidden. That setting is on for the organizations in scope. There is no fallback path: if this endpoint stops working, no PDF reaches the interface.

One last property, for anyone extending the integration beyond PDFs. Every monetary amount in this API is expressed in minor units, on read and on write, across every amount field. Nothing in the field naming says so, and the consequence for anyone comparing figures across systems is a uniform hundredfold discrepancy that looks like a data corruption and is not.

8.9 The Maxio (SaaSOptics) API

In plain language. Maxio is where the PDFs come from. The integration reads invoice metadata out of it, mostly to find one field: the link to the invoice PDF. It never writes anything, so a read-only token is enough.

Hosts and account paths. The four entities do not share one host.

Wide table: scroll it sideways.

The base URL is built as the host, then the account path, then the API version segment. Two consequences for routing. First, a client has to switch on the host and account path together, not on the account path alone: Limited is on one host, DACH on a second, Ireland and Denmark share a third. Store the four base URLs explicitly, paired with their credential, and never derive a host from an entity name. Second, the Denmark entity is internally labelled metacompliance_moch, a legacy naming artefact on MetaCompliance's side. The API recognises only that path, so it has to be preserved in the URL even though every human-facing reference calls the entity Denmark.

More generally, the entity names in this system are inconsistent and contain typographical errors. Do not string-match on entity names to build the mapping. Pair entities by currency and by their Upflow counterpart, and read the entity list from the API rather than from a screenshot.

Authentication. One header, using the literal scheme word Token. Not Bearer, and not HTTP Basic.

Authorization: Token <token>

Tokens are issued per entity in the administration settings, with a write-permission checkbox. This integration only reads, so a read-only token is sufficient and preferable.

Pagination. Responses carry a total count, a next link, a previous link, and a results array. The count is the total number of records matching the query and comes back on the first page without iterating, so a request for a single record is a cheap count-only probe. The largest page size observed is 100. The next and previous links are full absolute URLs, or null.

The invoice object, fields that matter here.

Two properties of number that mislead. First, the four-digit prefix is not the issue year: an invoice carrying a prefix several years old has been measured as issued recently, with a due date a month later. The prefix is most likely a fixed contract or template identifier, and that is a hypothesis. Never infer a document's age or its relevance from its number. Second, the invoice collection contains credit memos as well as invoices. Maxio keeps both in the same collection, and they are distinguishable only by the shape of the number: a credit memo ends in .CM. and digits, for example 2024-10687.CM.01. Credit memos do have their PDF link populated, so any "first record with a PDF" selection accepts one happily, and it then has to go to Upflow's credit note collection rather than to invoices. This is why the reference-shape test (section 8.5) runs before the lookup.

Future-dated invoices exist and distort sorting. Multi-year contracts are pre-booked, which produces invoices dated years ahead. Sorting by date descending therefore surfaces those first rather than the recently actionable ones. Sort by the modification timestamp descending for any query meaning "recent". Future-dated invoices normally have no PDF link, because they have not been e-billed yet.

The PDF link, and how a usable URL is built from it. The field is einvoicing_url_no_click_tracking. It is a public tokenised URL: no authentication is needed to fetch it, which is why the download node in every sync carries no credential.

Its base shape is https://<subdomain>.bills.saasoptics.com/p/i/{token}/?no_track, and that base URL serves the HTML viewer page, not the PDF. To get the PDF, the trailing /?no_track is replaced by /invoice.pdf?no_track. That single substitution is the rewrite rule listed in section 8.6, and it is applied in every sync.

When the field is empty. It is populated only once the invoice has actually been e-billed. Invoices predating e-billing adoption have it null, and so do future-dated pre-booked ones. Coverage measured on the largest entity, restricted to invoices modified since the start of 2025, was around 86 % on a 100-record sample, which is a sample-based figure and not a population measurement. Never assume full coverage; check the field before attempting a download. An empty field is what produces the no_einvoicing_url code in section 8.7.

What a good response looks like: content type application/pdf, the bytes %PDF- at the very start, and a size in the low tens of kilobytes for a typical one-page invoice. Validate both the magic bytes and a minimum size, because some tooling infers the content type from the .pdf in the URL rather than from the response header and will cheerfully report a PDF content type for an HTML error page. That is exactly what the validation stage does (section 4.4).

Token rotation is the operationally significant behaviour on this side, and it is fully characterised in section 5.9 rather than repeated here. The short version: the tokens in these links rotate silently, a rotated link answers with a redirect whose target drops the /invoice.pdf segment, and a client that follows redirects automatically downloads the viewer page and stores it as if it were the invoice.

Two consequences of all of the above that are visible in the architecture. First, there is no API-side way to scope to "invoices that have a PDF", so the cache builder fetches every invoice in the modification window and filters on the link being present, on its own side. Second, since the document number cannot be used as a filter, the cache is the only thing that turns an Upflow reference into a Maxio PDF link in one step. A cache miss is therefore a lookup failure, not proof that the invoice does not exist in Maxio: a document last modified outside the refresh window is absent from the cache while existing perfectly well upstream.

9. Making changes safely

In plain language. Everything before this section describes what the system is and how it behaves. This section is about touching it. It has three parts: 9.1 is how work is done here, and why each rule exists; 9.2 is the set of checks a change passes before and after it reaches production, each written so that it can be answered yes or no; 9.3 is the full procedure for adding a new organization, which is the extension this architecture was built to absorb.

Nothing here repeats the reference material. Where a rule or a gate depends on a fact, it points at the section that holds it.

9.1 The change discipline

Five rules. Each one exists because of something in this system that does not announce itself at edit time.

1. A change of shape is never made in place on a live workflow. A change of value is. The line runs between the two, and it is the line the system actually supports.

• Editing a value is applied in place, on the live workflow, and does not call for a clone. That covers a field in Set: Sync config, a cron expression, and a schedule. The workflow keeps its identity, its history and its settings, and reducing a schedule across the eleven scheduled workflows is eleven edits rather than eleven clones.
• Changing the shape is built on a clone and switched over. That covers adding or removing a node, rewiring a branch, and editing the source of a Code node. Clone the workflow, build the change on the clone, test the clone, then switch over: activate the clone and deactivate the original in the same sitting.

One boundary case, because the system has it and it is the one that gets read the wrong way. Some values are not in a configuration node at all, they are written inside Code node source: the mirrored exclusion values of rule 2 and the constants listed in rule 3. Changing one of those means editing source, so it sits on the shape side and goes on a clone, even though what is being changed looks like a value. The test is where the edit lands, not what the thing is called.

The reason the second case is held this firmly is that a shape change is the one that cannot be undone by reversing the edit. A saved workflow on this hosting model has no per-workflow version history to fall back on (rule 5), so the original left intact and switched off is the rollback, and gate G14 is what makes sure someone can still name it afterwards. A value edit is reversible by typing the old value back, which is why it does not carry the same weight.

Rename the superseded workflow at the moment of the switch, not when the clone is made. The [DEPRECATED v9.3.0] and [DEPRECATED v9.4.0] prefixes in section 8.1 are what a completed switch looks like. Applying that prefix earlier, while the workflow is still the one serving production, mislabels the instance for everyone who looks at it afterwards: the workflow list then says the live sync is retired and the retired one is live, which is exactly backwards at the moment someone is trying to work out what is actually running.

2. The exclusion logic is written twice inside every sync, and nothing keeps the copies in step. Code: Filter & match chain decides what is excluded; Code: Compute stats from filter inputs counts the same exclusions for the statistics. Since 2026-08-23 the two org-specific values they used to duplicate — the reference rule and the re-check window — are read from Set: Sync config by both, fail-loud, so the value can no longer drift between them. A change to the logic still has to land in both nodes in the same edit: changing only the filter leaves the coverage verdict describing something the run did not do; changing only the statistics node leaves the report wrong while behaviour is unchanged. The outstanding-state list also exists a third time, inside the chunk sub-workflow, and it has to agree with the parent (section 8.6).

3. Some values live inside Code node source, not in the configuration node. A maintainer who opens Set: Sync config, does not find a value there, and concludes it is not adjustable will be wrong every time. The second table in section 8.6 lists each of those constants, its value, and the node it lives in. One of them is not even in the same workflow: the Slack notification thresholds sit in a configuration node inside MC - Slack notify risks, and changing them changes alerting for every organization at once.

4. Renaming a node is not a cosmetic edit. Several nodes are read by name from expressions elsewhere in the same workflow, the name is matched as a literal string, and renaming one leaves the editor perfectly happy while breaking the workflow at runtime on the next scheduled tick. Section 4.4 carries the list of protected names and how many expressions point at each. Set: Sync config is the one to be most careful with: renaming it breaks the workflow everywhere at once, and the failure reads like a configuration problem rather than a rename.

5. The project keeps a versioned changelog, one section per workflow, held alongside this documentation rather than inside n8n. This is where the version numbers in the workflow names come from, and where the deprecated prefixes are explained. It is a separate file and it has to be handed over with this document, because the v9, v9-CM, v10 and v10.1 markers in the workflow names have no key without it.

The convention:

A successor should keep this going, and the reason is mechanical rather than tidy-minded. The n8n licence in use on this instance provides no built-in per-workflow change history, so this convention is the only record that exists of what changed on a workflow, when, and why. Without it, a sync that starts behaving differently after an edit is diagnosed by reading the current definition and guessing at the previous one.

9.2 The verification gates

In plain language. Each gate below is a check with a stated pass criterion, phrased so that the answer is yes or no rather than a matter of judgement. They are grouped by when they apply: before building, while building, before the change touches production, and after it is running. Every one of them corresponds to a way this system can fail quietly, and the failures they guard against are properties of the system as it stands today, not hypothetical ones.

A gate that cannot be answered yes has not been passed. "Probably fine" is not a pass, and neither is "the run was green", which is the specific answer several of these gates exist to reject.

Before building

While building

Before it touches production

After activation

9.3 Adding a new organization

In plain language. The architecture extends by cloning. A new legal entity gets its own credentials, its own cache table and its own three workflows, and nothing that already runs is edited. The work is mostly mechanical. The two places it goes wrong are the reference-format rule, which fails invisibly if it is inherited rather than measured, and the clone that keeps pointing at the source organization's data while carrying the new organization's name.

Prerequisites, and this is a stop rather than a list to skim

If any of these is missing, the work does not start. Cloning first and filling gaps afterwards means editing the same workflows twice, and the second edit is where mirrored values drift apart.

The steps, in order

Step 1. Measure the numbering convention. Read a handful of that entity's invoice references from its own Maxio account and compare them against the two shapes in force today: a four-digit prefix, a hyphen, then digits, which is how Limited and Ireland number; or plain integers, which is how DACH numbers (section 8.5). Write the answer down. It decides the rule in step 7, and it is the only step whose omission produces no symptom at all.

Verify: gate G1.

Step 2. Provision the two credentials. In the instance credential list, create an HTTP Custom Auth credential for Upflow and an HTTP Header Auth credential for Maxio. The Maxio authentication scheme word is the literal Token, not Bearer and not HTTP Basic (section 8.9). Follow the naming pattern already in use in section 8.3 so the list stays grouped by purpose and entity.

Verify: gate G2 for the Upflow side. On the Maxio side, a single count-only request against that entity's host and account path returns a total.

Step 3. Create the cache table. Create a data table named mc-so-cache-<slug> with the same eight columns as the four existing caches (section 8.2), types included — the two timestamp columns are deliberately string, because the data-table date type silently shifts timestamps under a non-UTC workflow timezone:

Verify: the column names and types match an existing cache exactly. The cache builder writes by column name, so a near-miss on a name is a write that goes nowhere.

Step 4. Seed the watermark row. The cache builders read their incremental watermark, the timestamp they last refreshed up to, from the shared mc-so-cache-progress table. Add one row for the new entity before the first run:

• window_key = __incremental_watermark_<slug>__
• status = pending
• every other column empty or zero

With the row present and empty, the first run falls back to an initial lookback window instead of failing on a missing row. The length of that fallback window is not stated in this document. Read it from the cache builder's own configuration before relying on it to decide whether a wider one-off backfill is needed.

Verify: the row exists, and its window_key matches, character for character, the value that goes into the cache builder configuration in step 5.

Step 5. Clone the cache builder. Source: MC - SO Cache builder v4 - incremental (Limited), which is active and current (section 8.1). Duplicate it and rename the duplicate MC - SO Cache builder v4 - incremental (<Entity>). Four edits on the clone:

1. Its configuration node: the org label becomes MetaCompliance <Entity>, the watermark row key becomes the value seeded in step 4, and the Maxio account path becomes the entity's own.
2. Its Maxio HTTP nodes: attach the new Maxio credential and set the host, because the host is per entity (section 8.9).
3. Its data table nodes: point them at mc-so-cache-<slug>.
4. Its schedule: pick the slot under gate G9, remembering that the cache has to be refreshed before the syncs that read it in the same cycle.

Verify: walk every data table node and every credential on the clone. A renamed workflow that still points at the source organization's cache table or credential looks entirely correct in the workflow list and writes to the wrong place.

Step 6. Clone the invoice sync. Clone from a current, active source only. Never clone from a name carrying [DEPRECATED], [GATED] or [PARKED] in section 8.1: those are kept as rollback references and they are behind the current generation.

Two cases, and they differ in how much there is to clone:

• Clone any of the three active invoice syncs (MC - Sync v10.1 - chunked pull all outstanding + redirect resolve, Limited / Ireland / DACH — section 8.1 has the IDs). The chunk sub-workflow has to be cloned too. On the sub-workflow clone, attach the new organization's Upflow credential: the credential and the name are the only things that differ between the sub-workflows that exist today (section 4.4). On the parent clone, point the Execute Sub-workflow: fetch + filter invoice chunk node at the sub-workflow clone, and leave its mode set to "Run once for each item", which is what makes each chunk a separate execution whose memory is released on return (section 4.4). The sub-workflow is published before the parent is activated (gate G10).

Edits on the parent clone, in both cases:

1. Set: Sync config: org becomes MetaCompliance <Entity>. Leave upflowBaseUrl alone. Set entityType to INVOICE for consistency, while knowing that nothing reads it: re-pointing a workflow by changing that value alone changes nothing at all (section 8.6).
2. Upflow HTTP nodes: attach the new credential on the count, the listing and the push, and on the sub-workflow's listing node if one was cloned.
3. The Maxio download node: no edit and no credential. Its URL comes from the cache row, and the link is a public tokenised URL (section 8.9).
4. The cache data table node: point it at mc-so-cache-<slug>.
5. The reference-format rule: step 7.
6. The schedule: gate G9.

Verify: the org value is exactly MetaCompliance <Entity> and is used by no other workflow on the instance; every Upflow credential on the clone is the new one; the cache node names the new table.

Step 7. Set the reference-format rule. Take the measurement from step 1 and write the matching pattern into nonSoPattern in Set: Sync config — since 2026-08-23 that one visible value is read by both the filter and its statistics mirror, fail-loud (section 8.5). There is no second place to edit and no code to open; an empty or invalid value stops the run instead of silently excluding everything.

One search trap on the way in: three of the four live filters write the pattern inline inside the test, while one assigns it to a named constant first, so searching the workflows for that constant name finds one rule and misses the others (section 8.5).

Verify: gate G5.

Step 8. Clone the credit note sync. Source: any of the three live ones, MC - Sync v10.1-CM - chunked pull all outstanding + redirect resolve (Limited / Ireland / DACH). They are identical apart from org labels and the cache table name; the CM chunk sub-workflow is cloned along with it, exactly as in step 6. Same edits as step 6, with two differences:

• The org value takes the CM suffix, so MetaCompliance <Entity> CM. That suffix is what keeps the invoice history and the credit note history apart in a shared log table, and it is deliberate rather than untidy (section 8.6).
• No organization-specific reference rule is involved. The credit note syncs require a reference ending in .CM. plus digits, which excludes the other shapes by construction (section 8.5). Do not add an outstanding-state test either: Upflow credit notes carry no state field, and a copied-over state test skips every credit note (section 8.8).

Verify: the org value carries the CM suffix, and the HTTP nodes point at the credit note paths rather than the invoice paths (section 8.8).

Step 9. Set the workflow settings on every clone. Cache builder, invoice sync, credit note sync, and the chunk sub-workflow if one was cloned. Two settings, read back after saving:

• The error workflow, gate G8. Sub-workflows included: the controlled test of 2026-08-23 established that the sub's own errorWorkflow is the only alert that names the real failure (section 4.3).
• The timezone, gate G7.

Step 10. Choose the schedule slots. Gate G9, for all three workflows at once, since they have to sit in the right order inside a cycle: cache builder first, then the invoice sync, then the credit note sync, or any order that keeps the cache ahead of its readers. Section 8.4 has the clock view and the free windows, including what a new organization does to them.

Step 11. Warm the cache before any sync reads it. Activate the cache builder, then trigger one manual run, and let it finish. This ordering is not a preference: a sync that runs against an empty cache logs every candidate as no_so_match_in_cache, which is time-bounded rather than permanent (section 8.7), so it heals on its own, but it fills the failure table and the weekly digest with a week of noise that means nothing.

Verify: mc-so-cache-<slug> has rows after the manual run, and einvoicing_url_no_click_tracking is populated on at least some of them. That field is only ever populated once an invoice has actually been e-billed, so a cache full of rows with an empty link column is a fact about the entity, not a defect (section 8.9).

Step 12. Rehearse, then activate the syncs.

If the entity is gated at launch, stop here. Leave both syncs inactive, with the [GATED] prefix in their names and the reason recorded, exactly as Denmark stands (section 7.1). The cache builder stays active, which is what keeps the cache warm for the day the entity is switched on.

Otherwise, in this order: gate G10 if a sub-workflow is involved, then gate G11 for the rehearsal, then gate G12 on the first pushes that rehearsal produced, and only then activate the invoice sync and the credit note sync.

Step 13. The observation window. The first cycle, the first day, and the first week each answer a different question.

Then close the loop on the documentation: add the new workflows, the new data table and the new credentials to the registry tables in section 8, add the new workflows to the schedule reference in section 8.4 (Table 1 for the three scheduled ones, Table 2 for a chunk sub-workflow), and open a changelog entry per new workflow under the convention in section 9.1.

Pitfalls that still apply

• The Maxio host varies per entity, and the account path is not derivable from the entity name. Section 8.9 has the table. Never build a base URL by pattern from an entity name, and store the host and the account path together with the credential they belong to.
• Entity naming in Maxio is inconsistent and contains typographical errors, and one entity is internally labelled with a legacy name that the API recognises and no human uses (section 8.9). Do not string-match on entity names to pair an entity with its credential. Pair by currency and by Upflow counterpart, and put the entity's identity in the credential label so the list stays readable.
• A duplicate made in the editor does not reliably carry the workflow settings across. Read the error workflow and the timezone back on the clone rather than assuming them, which is what gates G7 and G8 are for.
• The first run has a cold cache and a bounded lookback window. Outstanding invoices older than that window are absent from the cache, and each one logs as a cache miss until it re-enters the pool. The condition is time-bounded, not permanent (section 8.7), but a one-off wider backfill run of the cache builder avoids a week of failure rows that mean nothing.
• Test Mode is per Upflow organization and the flip out of it is irreversible. Read the new organization's current mode in its own Upflow settings rather than inferring it from the others, and treat going live as its own decision with its own checklist (sections 5.7 and 7.4).
• A COVERED verdict on a brand-new organization is a warning sign rather than a success. It is the same verdict an organization produces when its reference rule excluded everything (section 6.4).