E-Commerce — Integrations

OWNER: aimee (scoping) ALSO_USED_BY: anna (spec), urszula, maxim (backend), faye (PM Alfa), sytske (PM Bravo) LAST_VERIFIED: 2026-03-26

---

Overview

Most e-commerce projects require at least 3-5 third-party integrations: payment provider, shipping carrier, email service, and often accounting/ERP. Each integration adds scope, ongoing maintenance, and a failure surface. During scoping, Aimee must identify ALL required integrations early — late-discovered integrations are the #1 cause of scope creep.

---

Feature Decomposition

Shipping Carriers

SCOPE_ITEM: PostNL integration INCLUDES: Shipping label generation (Shipment API v4), barcode/tracking number, track & trace link, service point/pickup location lookup OPTIONAL: Address validation API, delivery date estimation, evening/weekend delivery, letterbox delivery (brievenbuspakje) COMPLIANCE: PostNL requires API key + customer code + customer number from client's business account ESTIMATE_COMPLEXITY: normal

SCOPE_ITEM: DHL Parcel NL integration INCLUDES: Label generation, tracking, service point lookup OPTIONAL: Same-day delivery (Amsterdam, Rotterdam, The Hague), DHL Express for international ESTIMATE_COMPLEXITY: normal

SCOPE_ITEM: DHL Express (international) INCLUDES: International label generation, customs documentation (CN23), tracking, duty/tax calculation COMPLIANCE: As of July 2026, EUR 3 flat-rate customs duty on all non-EU imports regardless of value ESTIMATE_COMPLEXITY: complex

SCOPE_ITEM: UPS integration INCLUDES: Label generation, tracking, rate calculation OPTIONAL: UPS Access Point (pickup locations), returns labels ESTIMATE_COMPLEXITY: normal

SCOPE_ITEM: Multi-carrier aggregator (Sendcloud (NL) PRIMARY / MyParcel) INCLUDES: Single API for PostNL + DHL + DPD + UPS, label generation, tracking, service point lookup, rate comparison OPTIONAL: Return portal, analytics dashboard COMPLIANCE: Client needs account with aggregator (separate contract and pricing) ESTIMATE_COMPLEXITY: normal

CHECK: Shipping integration approach IF: NL-only, single carrier → direct PostNL API integration IF: NL + Belgium, single carrier → direct PostNL API (cross-border supported) IF: multiple carriers or EU-wide → Sendcloud (NL, PRIMARY) or MyParcel aggregator IF: client already uses a carrier platform → integrate with their existing setup

Shipping Implementation Pattern

On order status → processing:
  1. Admin clicks "Create shipment" (or auto-trigger)
  2. Call carrier API to create shipment
  3. Receive barcode + label PDF
  4. Store tracking number on order
  5. Update order status → shipped
  6. Send shipping notification email with tracking link

On tracking update (webhook or poll):
  1. Carrier sends webhook (PostNL) or we poll status (DHL)
  2. Update tracking status in DB
  3. If delivered → update order status → delivered
  4. If failed delivery → alert admin

Email Service

SCOPE_ITEM: Transactional email INCLUDES: Order confirmation, shipping notification, password reset, email verification, refund confirmation OPTIONAL: Custom email templates with brand styling, email tracking (opens, clicks) ESTIMATE_COMPLEXITY: simple

CHECK: Transactional email provider IF: default → Brevo (FR) or Mailjet (FR) (EU-hosted, GDPR-native, good deliverability) IF: client explicitly requires US provider → Resend or Postmark (NOTE: US-based — EU data sovereignty risk) IF: client has existing → integrate with their provider (add sovereignty warning if US-based, e.g. SendGrid, Mailgun)

SCOPE_ITEM: Marketing email integration INCLUDES: Newsletter subscription (separate from transactional), subscriber sync to marketing platform, unsubscribe handling OPTIONAL: Automated flows (welcome series, abandoned cart, post-purchase), segmentation sync COMPLIANCE: GDPR — separate consent for marketing emails, double opt-in, easy unsubscribe ESTIMATE_COMPLEXITY: normal

CHECK: Marketing email platform IF: client has none → recommend Brevo (FR, EU-hosted, GDPR-native — PRIMARY). Mailchimp only if client explicitly demands (US-based — EU data sovereignty risk). IF: client has existing → API sync subscribers and order events (add sovereignty warning if US-based provider) IF: advanced automation needed → Klaviyo (best for e-commerce, expensive — US-based, add sovereignty warning)

Analytics

SCOPE_ITEM: Plausible Analytics (PRIMARY — EU) INCLUDES: Page views, referrers, basic conversion tracking, custom events COMPLIANCE: EU-hosted (Hetzner, Germany), cookie-free — no consent banner needed ESTIMATE_COMPLEXITY: simple

SCOPE_ITEM: Google Analytics 4 (GA4) (SECONDARY — US) INCLUDES: Page views, e-commerce events (view_item, add_to_cart, begin_checkout, purchase), conversion tracking, revenue reporting OPTIONAL: Enhanced e-commerce (product impressions, promotions), Google Ads conversion import COMPLIANCE: GDPR — GA4 requires cookie consent. Must not fire before consent. Consider server-side tagging with proxy for better data quality. NOTE: US-based service. Use only if client explicitly requires (e.g. Google Ads integration). EU data sovereignty risk. ESTIMATE_COMPLEXITY: normal

CHECK: Analytics approach IF: default → Plausible (EU-hosted, cookie-free, no consent banner needed) — PRIMARY IF: client needs Google Ads integration → GA4 behind consent wall (US-based — sovereignty warning to client) IF: both → Plausible for general + GA4 behind consent for ad tracking only

SCOPE_ITEM: Server-side analytics events INCLUDES: Purchase event fired server-side (not dependent on browser), ensures 100% conversion tracking regardless of ad blockers OPTIONAL: Server-side GA4 via Measurement Protocol, Meta Conversions API ESTIMATE_COMPLEXITY: normal

Tax Calculation

SCOPE_ITEM: Basic tax configuration INCLUDES: Tax rates per country (from config table), product tax category (standard, reduced, zero), tax calculation at checkout based on shipping country COMPLIANCE: EU VAT rates: NL 21%/9%, DE 19%/7%, FR 20%/5.5%, BE 21%/6% (see compliance.md for full table) ESTIMATE_COMPLEXITY: simple

SCOPE_ITEM: VAT validation (B2B) INCLUDES: VAT number input at checkout, VIES API validation, reverse charge for valid intra-EU B2B (0% VAT) COMPLIANCE: Must validate VAT number in real-time. Invalid = charge VAT. Store validation result for audit. ESTIMATE_COMPLEXITY: normal

CHECK: Tax complexity IF: NL-only → hardcode 21% standard, 9% reduced IF: EU cross-border B2C → VAT per destination country (OSS) IF: EU cross-border B2B → add VIES validation + reverse charge IF: international → consider tax service (but rare for SME clients)

Inventory Sync

SCOPE_ITEM: External inventory sync INCLUDES: Periodic sync from external system (ERP, warehouse, POS), stock level updates, conflict resolution (external system wins) OPTIONAL: Real-time sync via webhooks, bi-directional sync ESTIMATE_COMPLEXITY: complex

CHECK: Inventory source of truth IF: webshop-only → our DB is SSOT, no sync needed IF: webshop + physical store → POS system is SSOT, one-way sync to webshop IF: webshop + warehouse/3PL → warehouse system is SSOT, sync via API or file drop

ERP / Accounting Integration

SCOPE_ITEM: Exact Online integration INCLUDES: Order sync (push orders to Exact), invoice sync, customer sync, product sync OPTIONAL: Stock sync, financial reporting sync COMPLIANCE: Exact Online API uses OAuth 2.0, tokens expire every 10 minutes, must handle refresh ESTIMATE_COMPLEXITY: complex

SCOPE_ITEM: Moneybird integration INCLUDES: Invoice sync (push invoices to Moneybird), contact sync, payment reconciliation OPTIONAL: Estimate/quote sync, product sync ESTIMATE_COMPLEXITY: normal

SCOPE_ITEM: Generic accounting export INCLUDES: CSV/Excel export of orders, invoices, and payments per period, formatted for accountant import OPTIONAL: MT940 bank format export ESTIMATE_COMPLEXITY: simple

CHECK: Accounting integration IF: client uses Exact Online → API integration (complex, budget extra time) IF: client uses Moneybird → API integration (simpler, good docs) IF: client uses other / no preference → CSV export for accountant IF: client says "my accountant handles it" → CSV export, period

CMS / Content

SCOPE_ITEM: Blog / content pages INCLUDES: Simple page editor for about, contact, FAQ, blog posts, rich text + images OPTIONAL: SEO fields per page, scheduled publishing, categories/tags for blog ESTIMATE_COMPLEXITY: simple

CHECK: Content management approach IF: minimal pages (about, contact, FAQ) → built-in simple editor IF: active blog / content marketing → consider headless CMS (Payload CMS, self-hosted) IF: client wants to manage themselves → admin panel with WYSIWYG

Social Commerce

SCOPE_ITEM: Instagram Shopping INCLUDES: Product catalog sync to Meta Commerce Manager, product tags in posts/stories OPTIONAL: Instagram Checkout (US only as of 2026), shopping tab on profile COMPLIANCE: Meta Commerce policies, product data requirements ESTIMATE_COMPLEXITY: normal

SCOPE_ITEM: Google Merchant Center INCLUDES: Product feed generation (XML/RSS), automated feed updates, product data specification compliance OPTIONAL: Google Shopping ads integration, free product listings COMPLIANCE: Google product data specification (title, description, price, availability, GTIN) ESTIMATE_COMPLEXITY: normal

---

Integration Scoping Template

For every integration identified during scoping:

INTEGRATION: {name}
  PROVIDER: {company/service}
  DIRECTION: inbound | outbound | bidirectional
  FREQUENCY: real-time | near-real-time (webhook) | periodic (cron) | on-demand
  DATA: {what flows}
  AUTH: API key | OAuth 2.0 | webhook signature
  CLIENT_ACTION: {what client needs to provide/set up}
  ESTIMATE_COMPLEXITY: simple | normal | complex
  FAILURE_MODE: {what happens when this integration is down}

---

Anti-Patterns

ANTI_PATTERN: No retry logic for failed API calls FIX: Implement exponential backoff with max 3 retries. Queue failed calls for manual retry.

ANTI_PATTERN: Synchronous external API calls in the checkout flow FIX: Only Mollie payment creation is synchronous. Shipping label, analytics, email — all async.

ANTI_PATTERN: No webhook signature verification FIX: Verify all incoming webhooks. PostNL, Mollie, Stripe all have verification mechanisms.

ANTI_PATTERN: Hardcoded API credentials in code FIX: Environment variables or secrets manager. Never in git. Client's API keys in their environment only.

ANTI_PATTERN: Assuming external APIs are always available FIX: Design for failure. If PostNL is down, admin can still manage orders manually. If Exact is down, queue syncs.

---

Cross-References

READ_ALSO: wiki/docs/archetypes/e-commerce/payments.md READ_ALSO: wiki/docs/archetypes/e-commerce/order-management.md READ_ALSO: wiki/docs/archetypes/e-commerce/compliance.md READ_ALSO: wiki/docs/archetypes/e-commerce/product-catalog.md READ_ALSO: wiki/docs/archetypes/e-commerce/checklist.md READ_ALSO: wiki/docs/stack/hono/index.md