Testing Guide

This page is for anyone testing invoices against the AP Trial 3 sandbox — not for real customers, and not something you'd need if you were only using the live production system. It exists because this trial account's quirks (a deliberately truncated product catalog, a fixed set of canonical test invoices, a handful of confirmed differences from MOM) are stable facts about this specific environment, unlikely to change — worth writing down once instead of re-discovering the same things every time someone hits them.

This page is available to everyone for now, since testing is the current priority. It doesn't replace the real design documentation (features/invoices/spec.org, features/shipping/spec.org) — it points at that instead of repeating it, and links to real tracked issues instead of re-describing them here.

The canonical test invoices

Five curated invoices, each built to demonstrate one feature cleanly, each confirmed free of every catalog gap known at the time it was built. These are the ones to reach for first — not the full 51-invoice parity set (see below).

• DEMO-TIER-MULTI — multi-line volume pricing. Real source: MOM invoice 223634 (customer 182841).
• DEMO-TIER-100 — single-SKU volume pricing, the simplest tier story. Real source: MOM invoice 222550 (customer 265930).
• DEMO-BUNDLE — bundle-vs-breakout contrast (bundle expansion happens on the QBO side only, never HubSpot). Real source: MOM invoice 223695 (customer 268750).
• DEMO-ADDR-SPLIT — a real billing/shipping address divergence. Real source: MOM invoice 225616 (customer 270355, part of the INV06032026A.pdf batch).
• DEMO-BREAKOUT — breakout expansion, deliberately using a family not demonstrated elsewhere. No real MOM source — built fresh (SKU 208AP4, customer 269208) specifically to avoid a known catalog gap that hits every other breakout family used elsewhere.

The Tests page's Canonical tests mode lists these five, runs any of them live on the test pair, and shows the source MOM invoice beside HubSpot's invoice for the run (the registry the page reads is usertest/canonical.py, which restates this list).

All five live in features/invoices/tests/harness/test_demo_examples.py. Their generated PDFs are in features/invoices/assets/examples/, each alongside a copy of the closest matching real MOM original where one exists (named ORIGINAL-for-<demo-name>-<source-invoice>.pdf).

If you need a wider variety of shapes than these five cover — bundles and breakouts and tiers together, a specific catalog gap, a real Sales Tax line, etc. — see features/invoices/parity_invoice_index.org, a composition index of the full 51-invoice parity set. That's the fuller reference, not the canonical set — most of those 51 have never been checked for catalog gaps the way the five above have.

Checking whether a SKU is in this trial's catalog

AP Trial 3's product catalog is deliberately truncated — 243 of 392 real MOM SKUs, pruned because this trial plan can't hold accounts for the rest. A SKU that's missing produces a specific, confusing-looking symptom (see ISSUE-43 below), so checking first is worth it before assuming something else is wrong.

The full list is features/services/ap_trial_3_available_items.txt. To check one SKU:

grep "^SKU_HERE[[:space:]]" features/services/ap_trial_3_available_items.txt

No output means it's not in this trial's catalog. The file also shows each item's QBO type (Service or Inventory) — worth noting alongside ISSUE-44 below, since Service type alone doesn't reliably predict whether MOM actually taxes a given item.

Known, confirmed environment gaps

Real, filed issues — see the full list and current status at /issues. Linked here rather than re-described, so this page can't drift out of sync with the tracker:

• ISSUE-43 — a missing catalog SKU falls back to a generic, always-non-taxable QBO line item, silently dropping tax on that line.
• ISSUE-44 — this app currently treats every Service-typed QBO item as automatically non-taxable, but MOM's real order history shows that's wrong for at least two confirmed items (2025TOTV, 1730P).
• ISSUE-45 — a manually-typed recipient address can get silently overwritten by the associated Contact's stored address on the next revision, with no warning.
• ISSUE-46 — the revise-button status message can say "taking longer than usual" even after the revision already succeeded, if the status poll itself is broken rather than the revision.

Known, documented differences from MOM (not bugs)

Not every difference from a real MOM invoice is a problem — some are intentional, already-settled design decisions. Before assuming something is broken, check whether it's already documented as expected:

• Free-shipping and other order-level promos aren't modeled by the shipping placeholder before 2026-08-04 (see features/shipping/spec.org § Free Shipping (Checkbox Override) for the fix — needs the invoice's free_shipping checkbox set explicitly, it isn't automatic).
• Service-item shipping/tax exemption edge cases beyond ISSUE-44 above — see features/invoices/spec.org § Shipping Placeholder (HubSpot-Side), "Open question, deliberately deferred."
• features/invoices/parity_invoice_index.org has per-invoice notes on other confirmed-expected divergences (e.g. a real free-shipping promo not being reflected in the placeholder amount) found while building the full 51-invoice parity set.

PDF / invoice-number quirks

Checked directly against 10 real MOM source PDFs (features/invoices/assets/):

• The printed "Invoice No." isn't always just the plain number. Most print as <number>A (e.g. 223634A), but two checked so far (224044, 223756) print as <number>* instead. This isn't random — it correlates with the page being marked "SUMMARY COPY" rather than plain "COPY". Match on the numeric part when looking for an invoice, not the full printed string with its suffix.
• Some source PDFs are multi-page (224044, 223853, 224123 among those checked) — the real content, including priced lines, can be split across both pages. Check every page, not just the first.

Where the real documentation lives

This page is an index for testers, not a second copy of the design record. For the actual mechanics of shipping, tax, price tiers, bundles, and breakouts, go to features/invoices/spec.org and features/shipping/spec.org directly — those are kept current and detailed in a way this page deliberately isn't.