From 7c0b42e35d688a287998b36fa62ee76ec335d442 Mon Sep 17 00:00:00 2001
From: Bas van den Aakster <bvdaakster@gmail.com>
Date: Fri, 21 Nov 2025 15:35:12 +0100
Subject: [PATCH] fix: resolve plugin initialization failure in Next.js API
 routes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Use Symbol.for() instead of Symbol() for plugin singleton storage to ensure
plugin state persists across different module loading contexts (admin panel,
API routes, server components).

This fixes the "Billing plugin not initialized" error that occurred when
calling payload.create() from Next.js API routes, server components, or
server actions.

Changes:
- Plugin singleton now uses Symbol.for('@xtr-dev/payload-billing')
- Provider singletons (stripe, mollie, test) use global symbols
- Enhanced error message with troubleshooting guidance

Fixes #1

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 src/collections/hooks.ts | 3 ++-
 src/plugin/index.ts      | 2 +-
 src/providers/mollie.ts  | 2 +-
 src/providers/stripe.ts  | 2 +-
 src/providers/test.ts    | 2 +-
 5 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/src/collections/hooks.ts b/src/collections/hooks.ts
index 831c37f..302a28d 100644
--- a/src/collections/hooks.ts
+++ b/src/collections/hooks.ts
@@ -7,7 +7,8 @@ export const initProviderPayment = async (payload: Payload, payment: Partial<Pay
 
   if (!billing) {
     throw new Error(
-      'Billing plugin not initialized. Make sure the billingPlugin is properly configured in your Payload config and that Payload has finished initializing.'
+      'Billing plugin not initialized. Make sure the billingPlugin is properly configured in your Payload config and that Payload has finished initializing. ' +
+      'If you are calling this from a Next.js API route or Server Component, ensure you are using getPayload() with the same config instance used in your Payload configuration.'
     )
   }
 
diff --git a/src/plugin/index.ts b/src/plugin/index.ts
index d596507..b2bcb17 100644
--- a/src/plugin/index.ts
+++ b/src/plugin/index.ts
@@ -4,7 +4,7 @@ import type { Config, Payload } from 'payload'
 import { createSingleton } from './singleton'
 import type { PaymentProvider } from '../providers/index'
 
-const singleton = createSingleton(Symbol('billingPlugin'))
+const singleton = createSingleton(Symbol.for('@xtr-dev/payload-billing'))
 
 type BillingPlugin = {
   config: BillingPluginConfig
diff --git a/src/providers/mollie.ts b/src/providers/mollie.ts
index 23ecc80..e4d6b87 100644
--- a/src/providers/mollie.ts
+++ b/src/providers/mollie.ts
@@ -14,7 +14,7 @@ import {
 import { formatAmountForProvider, isValidAmount, isValidCurrencyCode } from './currency'
 import { createContextLogger } from '../utils/logger'
 
-const symbol = Symbol('mollie')
+const symbol = Symbol.for('@xtr-dev/payload-billing/mollie')
 export type MollieProviderConfig = Parameters<typeof createMollieClient>[0]
 
 /**
diff --git a/src/providers/stripe.ts b/src/providers/stripe.ts
index b6854cf..2af0ae9 100644
--- a/src/providers/stripe.ts
+++ b/src/providers/stripe.ts
@@ -14,7 +14,7 @@ import {
 import { isValidAmount, isValidCurrencyCode } from './currency'
 import { createContextLogger } from '../utils/logger'
 
-const symbol = Symbol('stripe')
+const symbol = Symbol.for('@xtr-dev/payload-billing/stripe')
 
 export interface StripeProviderConfig {
   secretKey: string
diff --git a/src/providers/test.ts b/src/providers/test.ts
index bb5105b..644e23d 100644
--- a/src/providers/test.ts
+++ b/src/providers/test.ts
@@ -6,7 +6,7 @@ import { handleWebhookError, logWebhookEvent } from './utils'
 import { isValidAmount, isValidCurrencyCode } from './currency'
 import { createContextLogger } from '../utils/logger'
 
-const TestModeWarningSymbol = Symbol('TestModeWarning')
+const TestModeWarningSymbol = Symbol.for('@xtr-dev/payload-billing/test-mode-warning')
 const hasGivenTestModeWarning = () => TestModeWarningSymbol in globalThis
 const setTestModeWarning = () => ((<any>globalThis)[TestModeWarningSymbol] = true)