feat(zettle): sync paid purchases into webshop_orders (#2445)

Community PR #2416 by @olofpinzke, adopted and finished by maintainers (rebased so every commit is signed).

Why the problem occurred: no Zettle integration; POS sales only reached the books as bank descriptors while Woo/Shopify already had order underlag via webshop_orders. The contributor's version also failed at the database (platform CHECKs listed only woocommerce/shopify), which the mocked unit tests never saw.
What was simplified: reused the Orders/book/invoice path instead of a new inbox; Finance API payouts/fees deferred. Sales the one-account, revenue-per-rate model cannot book (split tender, gift cards, tips) import unbookable with a "bokför manuellt" title instead of guessing accounts. Reset parity uses the rename-and-wrap pattern instead of re-issuing the reset body.
Why this solution: per-purchase rows give the radunderlag BFL verifikat need and the bulk-book path exists; daily kassarapport aggregation and Finance API fees/payouts are the follow-up (DECISIONS.md). Skeptic-refuted paths fixed before merge: concurrent refresh-token rotation (sync claim), cron offset paging (candidate snapshot), platform CHECKs, writer-role gate, migration-reset parity, white-label return origin re-validated at callback, VAT net from product rows.

Not live until ZETTLE_CLIENT_ID / ZETTLE_CLIENT_SECRET / ZETTLE_CREDENTIALS_ENCRYPTION_KEY are set on Vercel and a Zettle developer app is registered with the callback redirect URI.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WtYqzKPoTSRHskYYdf7MwB

lib/api/schemas.ts

@@ -1779,7 +1779,7 @@ export const BookTransactionSchema = z
 
 // ── Webshop orders (Orders page) ──────────────────────────────
 
-export const WebshopPlatformSchema = z.enum(['woocommerce', 'shopify'])
+export const WebshopPlatformSchema = z.enum(['woocommerce', 'shopify', 'zettle'])
 
 export const WebshopOrdersListQuerySchema = z.object({
   platform: WebshopPlatformSchema.optional(),

lib/dashboard/__tests__/nav-flags.test.ts

@@ -70,6 +70,7 @@ describe('getDashboardNavFlags', () => {
       'shopify_connections',
       'webshop_orders',
       'woocommerce_connections',
+      'zettle_connections',
     ])
   })
 

lib/dashboard/nav-flags.ts

@@ -70,15 +70,19 @@ export async function getDashboardNavFlagsViaProbes(
   supabase: SupabaseClient,
   companyId: string,
 ): Promise<Omit<DashboardNavFlags, 'hasExpenseClaims'>> {
-  const [woo, shopify, orders, trips] = await Promise.all([
+  const [woo, shopify, zettle, orders, trips] = await Promise.all([
     supabase.from('woocommerce_connections').select('id').eq('company_id', companyId).eq('status', 'active').limit(1),
     supabase.from('shopify_connections').select('id').eq('company_id', companyId).eq('status', 'active').limit(1),
+    supabase.from('zettle_connections').select('id').eq('company_id', companyId).eq('status', 'active').limit(1),
     supabase.from('webshop_orders').select('id').eq('company_id', companyId).limit(1),
     supabase.from('mileage_trips').select('id').eq('company_id', companyId).limit(1),
   ])
   return {
     hasWebshop:
-      (woo.data?.length ?? 0) > 0 || (shopify.data?.length ?? 0) > 0 || (orders.data?.length ?? 0) > 0,
+      (woo.data?.length ?? 0) > 0 ||
+      (shopify.data?.length ?? 0) > 0 ||
+      (zettle.data?.length ?? 0) > 0 ||
+      (orders.data?.length ?? 0) > 0,
     hasMileageTrips: (trips.data?.length ?? 0) > 0,
   }
 }

lib/entitlements/keys.ts

@@ -34,6 +34,8 @@ export const CAPABILITY = {
   woocommerce_sync: 'woocommerce_sync',
   /** Shopify store sync: orders/refunds imported as a transaction feed. */
   shopify_sync: 'shopify_sync',
+  /** Zettle purchase sync: paid purchases/refunds imported as a webshop_orders feed. */
+  zettle_sync: 'zettle_sync',
   /**
    * Multiple people working in one company. Without it only the OWNER can
    * enter the company: every other membership goes dormant (never deleted)
@@ -80,6 +82,7 @@ export const PAID_CAPABILITIES: readonly CapabilityKey[] = [
   CAPABILITY.stripe_payments,
   CAPABILITY.woocommerce_sync,
   CAPABILITY.shopify_sync,
+  CAPABILITY.zettle_sync,
   // Founder decision (2026-09-01): multiple users per company is paid.
   // Trial-seeded and Stripe-synced like the rest; enforcement is the
   // owner-only dormancy rule in lib/entitlements/multi-user.ts.

lib/events/types.ts

@@ -145,6 +145,9 @@ export type CoreEvent =
   // Shopify store lifecycle: same audit doctrine as stripe.*/woocommerce.*.
   | { type: 'shopify.connected'; payload: { connectionId: string; shopDomain: string; userId: string; companyId: string } }
   | { type: 'shopify.disconnected'; payload: { connectionId: string; shopDomain: string | null; reason: 'user' | 'revoked_upstream'; userId: string; companyId: string } }
+  // Zettle organization lifecycle: same audit doctrine as shopify.*.
+  | { type: 'zettle.connected'; payload: { connectionId: string; organizationUuid: string; userId: string; companyId: string } }
+  | { type: 'zettle.disconnected'; payload: { connectionId: string; organizationUuid: string | null; reason: 'user' | 'revoked_upstream'; userId: string; companyId: string } }
   // Periods
   | { type: 'period.locked'; payload: { period: FiscalPeriod; userId: string; companyId: string } }
   | { type: 'period.unlocked'; payload: { period: FiscalPeriod; userId: string; companyId: string } }

lib/extensions/__tests__/sectors.test.ts

@@ -48,8 +48,8 @@ describe('sectors registry', () => {
     expect(SECTORS.length).toBe(1)
   })
 
-  it('should have 18 total extensions', () => {
-    expect(getAllExtensions().length).toBe(18)
+  it('should have 19 total extensions', () => {
+    expect(getAllExtensions().length).toBe(19)
   })
 
   it('should have unique slugs within each sector', () => {
@@ -94,7 +94,7 @@ describe('sectors registry', () => {
 
   it('getExtensionsBySector returns extensions for a sector', () => {
     const extensions = getExtensionsBySector('general')
-    expect(extensions.length).toBe(18)
+    expect(extensions.length).toBe(19)
   })
 
   it('all extensions have required fields', () => {

lib/extensions/_generated/enabled-extensions.ts

@@ -15,5 +15,6 @@ export const ENABLED_EXTENSION_IDS: ReadonlySet<string> = new Set([
   'whatsapp-inbox',
   'woocommerce',
   'shopify',
+  'zettle',
   'mail',
 ])

lib/extensions/_generated/extension-list.ts

@@ -14,6 +14,7 @@ import { stripeExtension } from '@/extensions/general/stripe'
 import { whatsappInboxExtension } from '@/extensions/general/whatsapp-inbox'
 import { woocommerceExtension } from '@/extensions/general/woocommerce'
 import { shopifyExtension } from '@/extensions/general/shopify'
+import { zettleExtension } from '@/extensions/general/zettle'
 import { mailExtension } from '@/extensions/general/mail'
 
 export const FIRST_PARTY_EXTENSIONS: Extension[] = [
@@ -31,5 +32,6 @@ export const FIRST_PARTY_EXTENSIONS: Extension[] = [
   whatsappInboxExtension,
   woocommerceExtension,
   shopifyExtension,
+  zettleExtension,
   mailExtension,
 ]

lib/extensions/_generated/sector-definitions.ts

@@ -184,6 +184,17 @@ export const EXTENSION_DEFINITIONS: Record<string, ExtensionDefinition[]> = {
           "longDescription": "Anslut din Shopify-butik så hämtas betalda ordrar och återbetalningar automatiskt varje natt till Ordersidan, med belopp, betalsätt och moms per sats. Inget bokförs automatiskt: du bokför varje order själv från Ordersidan.",
           "hasOwnData": true
     },
+    {
+          "slug": "zettle",
+          "name": "Zettle",
+          "sector": "general",
+          "category": "import",
+          "icon": "CreditCard",
+          "dataPattern": "manual",
+          "description": "Hämta betalda köp och återbetalningar från Zettle till Ordersidan",
+          "longDescription": "Anslut ditt Zettle-konto så hämtas betalda köp och återbetalningar automatiskt varje natt till Ordersidan, med belopp, betalsätt, moms per sats och radunderlag. Inget bokförs automatiskt: du bokför varje köp själv från Ordersidan.",
+          "hasOwnData": true
+    },
     {
           "slug": "mail",
           "name": "Brevlådor",

lib/extensions/settings-panel-registry.tsx

@@ -25,6 +25,9 @@ const SETTINGS_PANELS: Record<string, ComponentType> = {
   shopify: dynamic(
     () => import('@/extensions/general/shopify/components/ShopifySettingsPanel')
   ),
+  zettle: dynamic(
+    () => import('@/extensions/general/zettle/components/ZettleSettingsPanel')
+  ),
 }
 
 /**

lib/reports/full-archive-export.ts

@@ -1252,6 +1252,7 @@ export const ARCHIVE_EXCLUDED_TABLES: Record<string, string> = {
   webhooks: 'automation config with signing secrets',
   woocommerce_connections: 'WooCommerce connection state (encrypted API secrets)',
   shopify_connections: 'Shopify connection state (encrypted API secrets)',
+  zettle_connections: 'Zettle connection state (encrypted OAuth refresh token)',
 }
 
 /** Max parent ids per `IN (...)` chunk: keeps the PostgREST URL well under limits. */

lib/stripe/__tests__/subscription-sync.test.ts

@@ -129,7 +129,7 @@ describe('applySubscriptionState', () => {
     const grantUpsert = calls.find((c) => c.table === 'capability_grants')
     expect(grantUpsert?.op).toBe('upsert')
     const rows = grantUpsert?.payload as Array<{ capability_key: string; source: string }>
-    expect(rows.map((r) => r.capability_key).sort()).toEqual(['ai', 'bank_sync', 'email_send', 'multi_user', 'shopify_sync', 'skatteverket', 'stripe_payments', 'woocommerce_sync'])
+    expect(rows.map((r) => r.capability_key).sort()).toEqual(['ai', 'bank_sync', 'email_send', 'multi_user', 'shopify_sync', 'skatteverket', 'stripe_payments', 'woocommerce_sync', 'zettle_sync'])
     expect(rows.every((r) => r.source === 'stripe')).toBe(true)
   })
 

lib/webshop-orders/order-underlag.tsx

@@ -58,6 +58,7 @@ export interface OrderUnderlagModel {
 const PLATFORM_LABELS: Record<string, string> = {
   woocommerce: 'WooCommerce',
   shopify: 'Shopify',
+  zettle: 'Zettle',
 }
 
 function vatRateLabel(rate: number | null): string {