Integration Expansion Roadmap

Date: 2026-02-26 Audience: Product, Engineering, Compliance, Operations Status: Draft

This document describes what must be added (without implementation code) to support:

• Alcohol distributor integrations
• Firearms serial-number verification workflows
• Purchaser background-check workflows
• QuickBooks integrations

This is a technical planning document, not legal advice.

1. Shared Platform Additions (Build Once, Reuse Across Integrations)

The new integration schema and endpoints are a good base. To support the next set of providers cleanly, add these shared capabilities:

0. Control-plane vs execution-plane boundary

• Keep configuration, IAM checks, and credential references in merchant-api (control plane).
• Run provider sync/webhook execution in tx-bundler (execution plane).
• Keep execution interfaces stable so runtime can later split into a dedicated worker service if needed.

1. Integration capability registry

• Add provider capability metadata (supports orders, catalog sync, webhooks, checks, etc.).
• Keep per-provider feature flags so each org/store can enable only approved capabilities.

2. Credential and token lifecycle

• Use secure references (credential_reference) only; never store raw secrets in app DB.
• Add token refresh health, expiry alarms, and manual re-auth workflow.

3. Sync orchestration and idempotency

• Background job framework for pull/push sync.
• Idempotency keys per provider operation.
• Dead-letter + replay for failed jobs.

4. Mapping and normalization layer

• Product/account/customer mapping tables between internal IDs and external IDs.
• Per-provider transform rules (units, taxes, account codes, enums).

5. Compliance evidence trail

• Immutable audit log for regulated decisions/actions.
• Include actor, timestamp, payload hash, external reference ID, and outcome.

6. Operational controls

• Dashboard for connection status, last sync result, error rates, queue depth.
• Runbooks and alert thresholds for production incidents.

2. Alcohol Distributor Integrations

Note: There is no single universal API for all alcohol distributors. Expect provider-by-provider adapters (API, EDI, SFTP, CSV).

Phase A0: Discovery and Compliance Gating

1. Define target distributors and protocol for each.
2. Add jurisdiction checks (federal/state/local) before enabling distributor ordering.
3. Define minimum required data:

• Store/license identifiers
• Distributor account number
• Product cross-reference (internal SKU <-> distributor SKU/UPC)
• Unit conversions (case, bottle, pack)

Phase A1: MVP Procurement Flow

1. Outbound purchase order flow:

• Create PO
• Submit to distributor
• Capture acknowledgment/rejection

2. Inbound shipment flow:

• Receive shipment notice (ASN or equivalent)
• Match to PO
• Partial receiving support

Phase A2: Financial and Inventory Reconciliation

1. Invoice ingestion and match against PO + received quantities.
2. Variance handling workflow (short ship, substitutions, pricing deltas).
3. Stock conversion and landed cost updates.

Phase A3: Hardening and Scale

1. Retry policy by error class (network, auth, validation, business reject).
2. Per-distributor observability and SLA reporting.
3. Store-level controls for approved categories/brands.

3. Firearms Serial-Number Verification Workflows

Important: This is highly regulated and must be designed with legal/compliance review from day one.

Phase B0: Compliance Model and Data Contract

1. Define serial lifecycle states:

• acquired
• in_stock
• reserved
• transferred
• returned
• disposed

2. Define required firearm metadata:

• manufacturer/importer
• model
• caliber/gauge
• type
• serial number
• acquisition/disposition references

Phase B1: Operational Validation MVP

1. Enforce serial uniqueness within required scope.
2. Add strict serial format/length validation by manufacturer/type rule.
3. Add transfer gate: no sale finalization without valid serial state and required metadata.

Phase B2: Verification and Escalation

1. Add “suspect serial” workflow with hold/review actions.
2. Record chain-of-custody events in immutable audit trail.
3. Add restricted admin views for sensitive data access.

Phase B3: Audit and Reporting

1. Build compliance export package for inspection/audits.
2. Add retention policy enforcement and tamper-evidence controls.
3. Add periodic reconciliation checks across inventory, sales, and serial ledger.

4. Purchaser Background-Check Workflows

Phase C0: Workflow Design and State Modeling

1. Add background-check state machine:

• initiated
• pending
• proceed
• delayed
• denied
• cancelled
• expired

2. Add required references:

• check request ID
• external transaction ID
• initiating employee
• timestamps

Phase C1: Checkout Gating MVP

1. Add transaction hold state until an allowed outcome is recorded.
2. Prevent completion for denied/expired outcomes.
3. Add supervisor override policy controls where legally allowed.

Phase C2: Jurisdiction and Timing Logic

1. Add routing rules for state POC vs federal workflow.
2. Add delayed-response handling and expiry windows.
3. Add re-check requirements for changed transaction conditions.

Phase C3: Compliance and Evidence

1. Immutable log of check requests and decisions.
2. Role-based access control for sensitive check data.
3. Retention and purge policies consistent with legal requirements.

5. QuickBooks Integrations

Treat accounting and payroll as separate capability modules even if both are Intuit-backed.

Phase D0: App Registration and Connection Contract

1. OAuth 2.0 connect flow, consent, token refresh, disconnect.
2. Capture and persist tenant reference (realmId) and granted scopes.
3. Add reconnect flow when scopes/tokens are invalid or downgraded.

Phase D1: MVP Accounting Sync

1. Outbound sync priorities:

• sales summaries or invoices
• payments/tenders
• tax
• refunds/returns

2. Inbound sync priorities:

• chart of accounts (read)
• customer/vendor references (if needed)

3. Add mapping UI/state:

• revenue accounts
• tax liability accounts
• payment clearing accounts

Phase D2: Payroll Extension (Optional Module)

1. Scope and data separation from accounting sync.
2. Employee/payroll entity mapping and sync boundaries.
3. Failure isolation so payroll issues do not break accounting sync.

Phase D3: Production Hardening

1. Webhook ingestion + change-data-capture fallback.
2. Idempotent writes and duplicate detection.
3. Reconciliation reports and manual replay tools.

6. Recommended Delivery Sequence

1. QuickBooks (lowest regulatory friction, high merchant value, fastest pilot path).
2. Alcohol distributors (medium complexity, provider diversity, inventory/PO value).
3. Firearms serial and background-check workflows (highest compliance burden, requires dedicated legal/compliance track).

7. Definition of Done (Per Integration Domain)

An integration is “done” only when all are true:

1. Functional

• Connect/disconnect works
• Required data flows complete successfully
• Retry and replay are available

2. Operational

• Dashboards and alerts exist
• Runbook exists and on-call can recover common failures

3. Compliance

• Required approvals are documented
• Audit trail is complete and queryable
• Retention/access controls are enforced

4. Commercial

• Pilot merchants validate workflow
• Support team has troubleshooting documentation