backend-manager 5.0.88 → 5.0.89

package/README.md

@@ -886,7 +886,7 @@ BEM includes a built-in payment/subscription system with Stripe integration (ext
 
 ### Unified Subscription Object
 
-The same subscription shape is stored in `users/{uid}.subscription` and `payments-subscriptions/{subId}.subscription`:
+The same subscription shape is stored in `users/{uid}.subscription` and `payments-orders/{orderId}.subscription`:
 
 ```javascript
 subscription: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.0.88",
+  "version": "5.0.89",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {

package/src/manager/events/firestore/payments-webhooks/on-write.js

@@ -8,8 +8,8 @@ const transitions = require('./transitions/index.js');
  * 1. Loads the processor library
  * 2. Fetches the latest resource from the processor API (not the stale webhook payload)
  * 3. Branches on event.category to transform + write:
- *    - subscription → toUnifiedSubscription → users/{uid}.subscription + payments-subscriptions/{resourceId}
- *    - one-time    → toUnifiedOneTime → payments-one-time/{resourceId}
+ *    - subscription → toUnifiedSubscription → users/{uid}.subscription + payments-orders/{orderId}
+ *    - one-time    → toUnifiedOneTime → payments-orders/{orderId}
  * 4. Detects state transitions and dispatches handler files (non-blocking)
  * 5. Marks the webhook as completed
  */
@@ -31,7 +31,7 @@ module.exports = async ({ Manager, assistant, change, context, libraries }) => {
 
   try {
     const processor = dataAfter.processor;
-    const uid = dataAfter.uid;
+    const uid = dataAfter.owner;
     const raw = dataAfter.raw;
     const eventType = dataAfter.event?.type;
     const category = dataAfter.event?.category;
@@ -70,13 +70,16 @@ module.exports = async ({ Manager, assistant, change, context, libraries }) => {
     const nowUNIX = powertools.timestamp(now, { output: 'unix' });
     const webhookReceivedUNIX = dataAfter.metadata?.received?.timestampUNIX || nowUNIX;
 
+    // Extract orderId from resource metadata (set at intent creation)
+    const orderId = resource.metadata?.orderId || null;
+
     // Branch on category
     let transitionName = null;
 
     if (category === 'subscription') {
-      transitionName = await processSubscription({ library, resource, uid, processor, eventType, eventId, resourceId, now, nowUNIX, webhookReceivedUNIX, admin, assistant, Manager });
+      transitionName = await processSubscription({ library, resource, uid, processor, eventType, eventId, resourceId, orderId, now, nowUNIX, webhookReceivedUNIX, admin, assistant, Manager });
     } else if (category === 'one-time') {
-      transitionName = await processOneTime({ library, resource, uid, processor, eventType, eventId, resourceId, now, nowUNIX, webhookReceivedUNIX, admin, assistant, Manager });
+      transitionName = await processOneTime({ library, resource, uid, processor, eventType, eventId, resourceId, orderId, now, nowUNIX, webhookReceivedUNIX, admin, assistant, Manager });
     } else {
       throw new Error(`Unknown event category: ${category}`);
     }
@@ -84,7 +87,8 @@ module.exports = async ({ Manager, assistant, change, context, libraries }) => {
     // Mark webhook as completed (include transition name for auditing/testing)
     await webhookRef.set({
       status: 'completed',
-      uid: uid,
+      owner: uid,
+      orderId: orderId,
       transition: transitionName,
       metadata: {
         processed: {
@@ -111,12 +115,12 @@ module.exports = async ({ Manager, assistant, change, context, libraries }) => {
  * 1. Read current user subscription (before state)
  * 2. Transform raw resource → unified subscription (after state)
  * 3. Detect and dispatch transition handlers (non-blocking)
- * 4. Write to user doc + payments-subscriptions
+ * 4. Write to user doc + payments-orders
  */
-async function processSubscription({ library, resource, uid, processor, eventType, eventId, resourceId, now, nowUNIX, webhookReceivedUNIX, admin, assistant, Manager }) {
-  // Staleness check: skip if a newer webhook already wrote to this resource
-  if (resourceId) {
-    const existingDoc = await admin.firestore().doc(`payments-subscriptions/${resourceId}`).get();
+async function processSubscription({ library, resource, uid, processor, eventType, eventId, resourceId, orderId, now, nowUNIX, webhookReceivedUNIX, admin, assistant, Manager }) {
+  // Staleness check: skip if a newer webhook already wrote to this order
+  if (orderId) {
+    const existingDoc = await admin.firestore().doc(`payments-orders/${orderId}`).get();
     if (existingDoc.exists) {
       const existingUpdatedUNIX = existingDoc.data()?.metadata?.updated?.timestampUNIX || 0;
       if (webhookReceivedUNIX < existingUpdatedUNIX) {
@@ -168,11 +172,14 @@ async function processSubscription({ library, resource, uid, processor, eventTyp
 
   assistant.log(`Updated users/${uid}.subscription: status=${unified.status}, product=${unified.product.id}`);
 
-  // Write to payments-subscriptions/{resourceId}
-  if (resourceId) {
-    await admin.firestore().doc(`payments-subscriptions/${resourceId}`).set({
-      uid: uid,
+  // Write to payments-orders/{orderId}
+  if (orderId) {
+    await admin.firestore().doc(`payments-orders/${orderId}`).set({
+      id: orderId,
+      type: 'subscription',
+      owner: uid,
       processor: processor,
+      resourceId: resourceId,
       subscription: unified,
       metadata: {
         created: {
@@ -192,7 +199,7 @@ async function processSubscription({ library, resource, uid, processor, eventTyp
       },
     }, { merge: true });
 
-    assistant.log(`Updated payments-subscriptions/${resourceId}: uid=${uid}, eventType=${eventType}`);
+    assistant.log(`Updated payments-orders/${orderId}: type=subscription, uid=${uid}, eventType=${eventType}`);
   }
 
   return transitionName;
@@ -202,12 +209,12 @@ async function processSubscription({ library, resource, uid, processor, eventTyp
  * Process a one-time payment event
  * 1. Transform raw resource → unified one-time
  * 2. Detect and dispatch transition handlers (non-blocking)
- * 3. Write to payments-one-time
+ * 3. Write to payments-orders
  */
-async function processOneTime({ library, resource, uid, processor, eventType, eventId, resourceId, now, nowUNIX, webhookReceivedUNIX, admin, assistant, Manager }) {
-  // Staleness check: skip if a newer webhook already wrote to this resource
-  if (resourceId) {
-    const existingDoc = await admin.firestore().doc(`payments-one-time/${resourceId}`).get();
+async function processOneTime({ library, resource, uid, processor, eventType, eventId, resourceId, orderId, now, nowUNIX, webhookReceivedUNIX, admin, assistant, Manager }) {
+  // Staleness check: skip if a newer webhook already wrote to this order
+  if (orderId) {
+    const existingDoc = await admin.firestore().doc(`payments-orders/${orderId}`).get();
     if (existingDoc.exists) {
       const existingUpdatedUNIX = existingDoc.data()?.metadata?.updated?.timestampUNIX || 0;
       if (webhookReceivedUNIX < existingUpdatedUNIX) {
@@ -250,11 +257,14 @@ async function processOneTime({ library, resource, uid, processor, eventType, ev
     trackPayment({ category: 'one-time', transitionName, unified, uid, processor, assistant, Manager });
   }
 
-  // Write to payments-one-time/{resourceId}
-  if (resourceId) {
-    await admin.firestore().doc(`payments-one-time/${resourceId}`).set({
-      uid: uid,
+  // Write to payments-orders/{orderId}
+  if (orderId) {
+    await admin.firestore().doc(`payments-orders/${orderId}`).set({
+      id: orderId,
+      type: 'one-time',
+      owner: uid,
       processor: processor,
+      resourceId: resourceId,
       payment: unified,
       metadata: {
         created: {
@@ -274,7 +284,7 @@ async function processOneTime({ library, resource, uid, processor, eventType, ev
       },
     }, { merge: true });
 
-    assistant.log(`Updated payments-one-time/${resourceId}: uid=${uid}, eventType=${eventType}`);
+    assistant.log(`Updated payments-orders/${orderId}: type=one-time, uid=${uid}, eventType=${eventType}`);
   }
 
   return transitionName;

package/src/manager/helpers/user.js

@@ -38,6 +38,7 @@ const SCHEMA = {
     },
     payment: {
       processor: { type: 'string', default: null, nullable: true },
+      orderId: { type: 'string', default: null, nullable: true },
       resourceId: { type: 'string', default: null, nullable: true },
       frequency: { type: 'string', default: null, nullable: true },
       startDate: '$timestamp',

package/src/manager/libraries/payment-processors/order-id.js

@@ -0,0 +1,18 @@
+const crypto = require('crypto');
+
+/**
+ * Generate a unique order ID in the format XXXX-XXXX-XXXX
+ * 12 random digits, grouped in 3 segments of 4
+ *
+ * @returns {string} e.g. '4637-8821-0473'
+ */
+function generate() {
+  const bytes = crypto.randomBytes(6);
+  const digits = Array.from(bytes)
+    .map(b => (b % 100).toString().padStart(2, '0'))
+    .join('');
+
+  return `${digits.slice(0, 4)}-${digits.slice(4, 8)}-${digits.slice(8, 12)}`;
+}
+
+module.exports = { generate };

package/src/manager/libraries/payment-processors/stripe.js

@@ -115,6 +115,7 @@ const Stripe = {
       cancellation: cancellation,
       payment: {
         processor: 'stripe',
+        orderId: rawSubscription.metadata?.orderId || null,
         resourceId: rawSubscription.id || null,
         frequency: frequency,
         startDate: startDate,
@@ -149,6 +150,7 @@ const Stripe = {
     return {
       id: rawResource.id || null,
       processor: 'stripe',
+      orderId: rawResource.metadata?.orderId || null,
       status: rawResource.status || 'unknown',
       raw: rawResource,
       metadata: {

package/src/manager/libraries/payment-processors/test.js

@@ -26,15 +26,18 @@ const Test = {
       return rawFallback;
     }
 
-    // Fallback doesn't match — try to look up the resource from Firestore
+    // Fallback doesn't match — try to look up the resource from payments-orders
     const admin = context?.admin;
     if (admin && resourceId) {
-      const collection = resourceType === 'subscription' ? 'payments-subscriptions' : 'payments-one-time';
-      const doc = await admin.firestore().doc(`${collection}/${resourceId}`).get();
-
-      if (doc.exists) {
-        const data = doc.data();
-        // payments-subscriptions stores the unified subscription inside .subscription
+      const snapshot = await admin.firestore()
+        .collection('payments-orders')
+        .where('resourceId', '==', resourceId)
+        .limit(1)
+        .get();
+
+      if (!snapshot.empty) {
+        const data = snapshot.docs[0].data();
+        // payments-orders stores the unified subscription inside .subscription
         // Reconstruct a Stripe-shaped object from the unified data for toUnifiedSubscription()
         if (resourceType === 'subscription' && data.subscription) {
           return buildStripeSubscriptionFromUnified(data.subscription, resourceId, context?.eventType, context?.config);
@@ -110,7 +113,7 @@ function buildStripeSubscriptionFromUnified(unified, resourceId, eventType, conf
     id: resourceId,
     object: 'subscription',
     status: status,
-    metadata: {},
+    metadata: { orderId: unified.payment?.orderId || null },
     plan: {
       id: priceId,
       interval: INTERVAL_MAP[frequency] || 'month',

package/src/manager/routes/payments/intent/post.js

@@ -1,5 +1,6 @@
 const path = require('path');
 const powertools = require('node-powertools');
+const OrderId = require('../../../libraries/payment-processors/order-id.js');
 
 /**
  * POST /payments/intent
@@ -49,8 +50,9 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
     // Resolve trial eligibility: if requested but user has subscription history, silently downgrade
     if (trial) {
       const historySnapshot = await admin.firestore()
-        .collection('payments-subscriptions')
-        .where('uid', '==', uid)
+        .collection('payments-orders')
+        .where('owner', '==', uid)
+        .where('type', '==', 'subscription')
         .limit(1)
         .get();
 
@@ -64,6 +66,11 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
     trial = false;
   }
 
+  // Generate order ID
+  const orderId = OrderId.generate();
+
+  assistant.log(`Generated orderId=${orderId}`);
+
   // Load the processor module
   let processorModule;
   try {
@@ -77,6 +84,7 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
   try {
     result = await processorModule.createIntent({
       uid,
+      orderId,
       product,
       productId,
       frequency,
@@ -96,11 +104,12 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
   const now = powertools.timestamp(new Date(), { output: 'string' });
   const nowUNIX = powertools.timestamp(now, { output: 'unix' });
 
-  // Save to payments-intents collection
-  await admin.firestore().doc(`payments-intents/${result.id}`).set({
-    id: result.id,
+  // Save to payments-intents collection (keyed by orderId for consistent lookup with payments-orders)
+  await admin.firestore().doc(`payments-intents/${orderId}`).set({
+    id: orderId,
+    intentId: result.id,
     processor: processor,
-    uid: uid,
+    owner: uid,
     status: 'pending',
     productId: productId,
     productType: productType,
@@ -115,10 +124,11 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
     },
   });
 
-  assistant.log(`Saved payments-intents/${result.id}: uid=${uid}, product=${productId}, type=${productType}, frequency=${frequency}, trial=${trial}`);
+  assistant.log(`Saved payments-intents/${orderId}: uid=${uid}, product=${productId}, type=${productType}, frequency=${frequency}, trial=${trial}`);
 
   return assistant.respond({
     id: result.id,
+    orderId: orderId,
     url: result.url,
   });
 };

package/src/manager/routes/payments/intent/processors/stripe.js

@@ -16,7 +16,7 @@ module.exports = {
    * @param {object} options.Manager - Manager instance
    * @returns {object} { id, url, raw }
    */
-  async createIntent({ uid, product, productId, frequency, trial, config, Manager, assistant }) {
+  async createIntent({ uid, orderId, product, productId, frequency, trial, config, Manager, assistant }) {
     // Initialize Stripe SDK
     const StripeLib = require('../../../../libraries/payment-processors/stripe.js');
     const stripe = StripeLib.init();
@@ -57,10 +57,9 @@ module.exports = {
     confirmationUrl.searchParams.set('frequency', frequency || 'once');
     confirmationUrl.searchParams.set('paymentMethod', 'stripe');
     confirmationUrl.searchParams.set('trial', String(!!trial && !!product.trial?.days));
+    confirmationUrl.searchParams.set('orderId', orderId);
     confirmationUrl.searchParams.set('track', 'true');
-    // Append orderId as raw string — Stripe replaces {CHECKOUT_SESSION_ID} at redirect
-    // time, but only if the braces are NOT URL-encoded
-    confirmationUrl = `${confirmationUrl.toString()}&orderId={CHECKOUT_SESSION_ID}`;
+    confirmationUrl = confirmationUrl.toString();
 
     let cancelUrl = new URL('/payment/checkout', baseUrl);
     cancelUrl.searchParams.set('product', productId);
@@ -74,9 +73,9 @@ module.exports = {
     let sessionParams;
 
     if (productType === 'subscription') {
-      sessionParams = buildSubscriptionSession({ priceId, customer, uid, productId, frequency, trial, product, confirmationUrl, cancelUrl });
+      sessionParams = buildSubscriptionSession({ priceId, customer, uid, orderId, productId, frequency, trial, product, confirmationUrl, cancelUrl });
     } else {
-      sessionParams = buildOneTimeSession({ priceId, customer, uid, productId, product, confirmationUrl, cancelUrl });
+      sessionParams = buildOneTimeSession({ priceId, customer, uid, orderId, productId, product, confirmationUrl, cancelUrl });
     }
 
     // Create the checkout session
@@ -95,7 +94,7 @@ module.exports = {
 /**
  * Build Stripe Checkout Session params for a subscription
  */
-function buildSubscriptionSession({ priceId, customer, uid, productId, frequency, trial, product, confirmationUrl, cancelUrl }) {
+function buildSubscriptionSession({ priceId, customer, uid, orderId, productId, frequency, trial, product, confirmationUrl, cancelUrl }) {
   const sessionParams = {
     mode: 'subscription',
     customer: customer.id,
@@ -106,12 +105,14 @@ function buildSubscriptionSession({ priceId, customer, uid, productId, frequency
     subscription_data: {
       metadata: {
         uid: uid,
+        orderId: orderId,
       },
     },
     success_url: confirmationUrl,
     cancel_url: cancelUrl,
     metadata: {
       uid: uid,
+      orderId: orderId,
       productId: productId,
       frequency: frequency,
     },
@@ -128,7 +129,7 @@ function buildSubscriptionSession({ priceId, customer, uid, productId, frequency
 /**
  * Build Stripe Checkout Session params for a one-time payment
  */
-function buildOneTimeSession({ priceId, customer, uid, productId, product, confirmationUrl, cancelUrl }) {
+function buildOneTimeSession({ priceId, customer, uid, orderId, productId, product, confirmationUrl, cancelUrl }) {
   return {
     mode: 'payment',
     customer: customer.id,
@@ -139,12 +140,14 @@ function buildOneTimeSession({ priceId, customer, uid, productId, product, confi
     payment_intent_data: {
       metadata: {
         uid: uid,
+        orderId: orderId,
       },
     },
     success_url: confirmationUrl,
     cancel_url: cancelUrl,
     metadata: {
       uid: uid,
+      orderId: orderId,
       productId: productId,
     },
   };

package/src/manager/routes/payments/intent/processors/test.js

@@ -21,7 +21,7 @@ module.exports = {
    * @param {object} options.assistant - Assistant instance
    * @returns {object} { id, url, raw }
    */
-  async createIntent({ uid, product, productId, frequency, trial, config, Manager, assistant }) {
+  async createIntent({ uid, orderId, product, productId, frequency, trial, config, Manager, assistant }) {
     // Guard: test processor is not available in production
     if (assistant.isProduction()) {
       throw new Error('Test processor is not available in production');
@@ -30,10 +30,10 @@ module.exports = {
     const productType = product.type || 'subscription';
 
     if (productType === 'subscription') {
-      return createSubscriptionIntent({ uid, product, productId, frequency, trial, config, Manager, assistant });
+      return createSubscriptionIntent({ uid, orderId, product, productId, frequency, trial, config, Manager, assistant });
     }
 
-    return createOneTimeIntent({ uid, product, productId, config, Manager, assistant });
+    return createOneTimeIntent({ uid, orderId, product, productId, config, Manager, assistant });
   },
 };
 
@@ -41,7 +41,7 @@ module.exports = {
  * Create a test subscription intent
  * Generates Stripe-shaped subscription + customer.subscription.created event
  */
-async function createSubscriptionIntent({ uid, product, productId, frequency, trial, config, Manager, assistant }) {
+async function createSubscriptionIntent({ uid, orderId, product, productId, frequency, trial, config, Manager, assistant }) {
   // Get the price ID for the requested frequency
   const priceId = product.prices?.[frequency]?.stripe;
   if (!priceId) {
@@ -68,7 +68,7 @@ async function createSubscriptionIntent({ uid, product, productId, frequency, tr
     id: subscriptionId,
     object: 'subscription',
     status: trial && product.trial?.days ? 'trialing' : 'active',
-    metadata: { uid },
+    metadata: { uid, orderId },
     plan: { id: priceId, interval },
     current_period_end: periodEnd,
     current_period_start: now,
@@ -110,7 +110,7 @@ async function createSubscriptionIntent({ uid, product, productId, frequency, tr
  * Create a test one-time payment intent
  * Generates Stripe-shaped checkout session + checkout.session.completed event
  */
-async function createOneTimeIntent({ uid, product, productId, config, Manager, assistant }) {
+async function createOneTimeIntent({ uid, orderId, product, productId, config, Manager, assistant }) {
   // Get the price ID for one-time purchase
   const priceId = product.prices?.once?.stripe;
   if (!priceId) {
@@ -129,7 +129,7 @@ async function createOneTimeIntent({ uid, product, productId, config, Manager, a
     mode: 'payment',
     status: 'complete',
     payment_status: 'paid',
-    metadata: { uid, productId },
+    metadata: { uid, orderId, productId },
     amount_total: Math.round((product.prices?.once?.amount || 0) * 100),
     currency: 'usd',
   };

package/src/manager/routes/payments/webhook/post.js

@@ -82,7 +82,7 @@ module.exports = async ({ assistant, Manager, libraries }) => {
     processor: processor,
     status: 'pending',
     raw: raw,
-    uid: uid,
+    owner: uid,
     event: {
       type: eventType,
       category: category,

package/src/test/test-accounts.js

@@ -363,13 +363,13 @@ async function deleteTestUsers(admin) {
 
   // Clean up payment-related collections for test accounts
   const testUids = Object.values(TEST_ACCOUNTS).map(a => a.uid);
-  const paymentCollections = ['payments-subscriptions', 'payments-webhooks', 'payments-intents', 'payments-one-time'];
+  const paymentCollections = ['payments-orders', 'payments-webhooks', 'payments-intents'];
 
   await Promise.all(
     paymentCollections.map(async (collection) => {
       try {
         const snapshot = await admin.firestore().collection(collection)
-          .where('uid', 'in', testUids)
+          .where('owner', 'in', testUids)
           .get();
 
         await Promise.all(

package/test/events/payments/journey-payments-cancel.js

@@ -32,6 +32,7 @@ module.exports = {
           frequency: 'monthly',
         });
         assert.isSuccess(response, 'Intent should succeed');
+        state.orderId = response.data.orderId;
 
         // Wait for subscription to activate
         await waitFor(async () => {
@@ -42,6 +43,7 @@ module.exports = {
         const userDoc = await firestore.get(`users/${uid}`);
         assert.equal(userDoc.subscription?.product?.id, paidProduct.id, `Should start as ${paidProduct.id}`);
         assert.equal(userDoc.subscription?.status, 'active', 'Should be active');
+        assert.equal(userDoc.subscription?.payment?.orderId, state.orderId, 'Order ID should match intent');
 
         state.subscriptionId = userDoc.subscription.payment.resourceId;
       },

package/test/events/payments/journey-payments-failure.js

@@ -35,6 +35,7 @@ module.exports = {
           frequency: 'monthly',
         });
         assert.isSuccess(response, 'Intent should succeed');
+        state.orderId = response.data.orderId;
 
         // Wait for subscription to activate
         await waitFor(async () => {
@@ -45,6 +46,7 @@ module.exports = {
         const userDoc = await firestore.get(`users/${uid}`);
         assert.equal(userDoc.subscription?.product?.id, paidProduct.id, `Should start as ${paidProduct.id}`);
         assert.equal(userDoc.subscription?.status, 'active', 'Should be active');
+        assert.equal(userDoc.subscription?.payment?.orderId, state.orderId, 'Order ID should match intent');
 
         state.subscriptionId = userDoc.subscription.payment.resourceId;
       },

package/test/events/payments/journey-payments-suspend.js

@@ -32,6 +32,7 @@ module.exports = {
           frequency: 'monthly',
         });
         assert.isSuccess(response, 'Intent should succeed');
+        state.orderId = response.data.orderId;
 
         // Wait for subscription to activate
         await waitFor(async () => {
@@ -42,6 +43,7 @@ module.exports = {
         const userDoc = await firestore.get(`users/${uid}`);
         assert.equal(userDoc.subscription?.product?.id, paidProduct.id, `Should start as ${paidProduct.id}`);
         assert.equal(userDoc.subscription?.status, 'active', 'Should be active');
+        assert.equal(userDoc.subscription?.payment?.orderId, state.orderId, 'Order ID should match intent');
 
         state.subscriptionId = userDoc.subscription.payment.resourceId;
       },

package/test/events/payments/journey-payments-trial.js

@@ -43,8 +43,10 @@ module.exports = {
 
         assert.isSuccess(response, 'Intent should succeed');
         assert.ok(response.data.id, 'Should return intent ID');
+        assert.ok(response.data.orderId, 'Should return orderId');
 
         state.intentId = response.data.id;
+        state.orderId = response.data.orderId;
 
         // Derive webhook event ID from intent ID (same timestamp)
         state.eventId = response.data.id.replace('_test-cs-', '_test-evt-');
@@ -65,6 +67,7 @@ module.exports = {
         assert.equal(userDoc.subscription.product.id, state.paidProductId, `Product should be ${state.paidProductId}`);
         assert.equal(userDoc.subscription.status, 'active', 'Status should be active');
         assert.equal(userDoc.subscription.trial.claimed, true, 'Trial should be claimed');
+        assert.equal(userDoc.subscription.payment.orderId, state.orderId, 'Order ID should match intent');
 
         state.subscriptionId = userDoc.subscription.payment.resourceId;
 
@@ -72,6 +75,7 @@ module.exports = {
         const webhookDoc = await firestore.get(`payments-webhooks/${state.eventId}`);
         assert.ok(webhookDoc, 'Webhook doc should exist');
         assert.equal(webhookDoc.transition, 'new-subscription', 'Transition should be new-subscription (trial detected inside handler)');
+        assert.equal(webhookDoc.orderId, state.orderId, 'Webhook doc orderId should match intent');
       },
     },
 

package/test/events/payments/journey-payments-upgrade.js

@@ -42,9 +42,12 @@ module.exports = {
 
         assert.isSuccess(response, 'Intent should succeed');
         assert.ok(response.data.id, 'Should return intent ID');
+        assert.ok(response.data.orderId, 'Should return orderId');
+        assert.match(response.data.orderId, /^\d{4}-\d{4}-\d{4}$/, 'orderId should be XXXX-XXXX-XXXX format');
         assert.ok(response.data.url, 'Should return URL');
 
         state.intentId = response.data.id;
+        state.orderId = response.data.orderId;
 
         // Derive webhook event ID from intent ID (same timestamp)
         state.eventId = response.data.id.replace('_test-cs-', '_test-evt-');
@@ -65,6 +68,7 @@ module.exports = {
         assert.equal(userDoc.subscription.product.id, state.paidProductId, `Product should be ${state.paidProductId}`);
         assert.equal(userDoc.subscription.status, 'active', 'Status should be active');
         assert.equal(userDoc.subscription.payment.processor, 'test', 'Processor should be test');
+        assert.equal(userDoc.subscription.payment.orderId, state.orderId, 'Order ID should match intent');
         assert.ok(userDoc.subscription.payment.resourceId, 'Resource ID should be set');
         assert.equal(userDoc.subscription.payment.frequency, 'monthly', 'Frequency should be monthly');
         assert.equal(userDoc.subscription.cancellation.pending, false, 'Should not be pending cancellation');
@@ -74,15 +78,18 @@ module.exports = {
     },
 
     {
-      name: 'subscription-doc-created',
+      name: 'order-doc-created',
       async run({ firestore, assert, state }) {
-        const subDoc = await firestore.get(`payments-subscriptions/${state.subscriptionId}`);
-
-        assert.ok(subDoc, 'Subscription doc should exist');
-        assert.equal(subDoc.uid, state.uid, 'UID should match');
-        assert.equal(subDoc.processor, 'test', 'Processor should be test');
-        assert.equal(subDoc.subscription.product.id, state.paidProductId, `Product should be ${state.paidProductId}`);
-        assert.equal(subDoc.subscription.status, 'active', 'Status should be active');
+        const orderDoc = await firestore.get(`payments-orders/${state.orderId}`);
+
+        assert.ok(orderDoc, 'Order doc should exist');
+        assert.equal(orderDoc.id, state.orderId, 'ID should match orderId');
+        assert.equal(orderDoc.type, 'subscription', 'Type should be subscription');
+        assert.equal(orderDoc.owner, state.uid, 'Owner should match');
+        assert.equal(orderDoc.processor, 'test', 'Processor should be test');
+        assert.equal(orderDoc.resourceId, state.subscriptionId, 'Resource ID should match');
+        assert.equal(orderDoc.subscription.product.id, state.paidProductId, `Product should be ${state.paidProductId}`);
+        assert.equal(orderDoc.subscription.status, 'active', 'Status should be active');
       },
     },
 
@@ -97,16 +104,19 @@ module.exports = {
         const webhookDoc = await firestore.get(`payments-webhooks/${state.eventId}`);
         assert.ok(webhookDoc, 'Webhook doc should exist');
         assert.equal(webhookDoc.transition, 'new-subscription', 'Transition should be new-subscription');
+        assert.equal(webhookDoc.orderId, state.orderId, 'Webhook doc orderId should match intent');
       },
     },
 
     {
       name: 'intent-doc-created',
       async run({ firestore, assert, state }) {
-        const intentDoc = await firestore.get(`payments-intents/${state.intentId}`);
+        const intentDoc = await firestore.get(`payments-intents/${state.orderId}`);
 
         assert.ok(intentDoc, 'Intent doc should exist');
-        assert.equal(intentDoc.uid, state.uid, 'UID should match');
+        assert.equal(intentDoc.id, state.orderId, 'ID should match orderId');
+        assert.equal(intentDoc.intentId, state.intentId, 'Intent ID should match processor session ID');
+        assert.equal(intentDoc.owner, state.uid, 'Owner should match');
         assert.equal(intentDoc.processor, 'test', 'Processor should be test');
         assert.equal(intentDoc.status, 'pending', 'Intent status should be pending');
         assert.equal(intentDoc.productId, state.paidProductId, `Product should be ${state.paidProductId}`);

package/test/helpers/stripe-to-unified.js

@@ -365,6 +365,22 @@ module.exports = {
       },
     },
 
+    {
+      name: 'payment-order-id-from-metadata',
+      async run({ assert }) {
+        const result = toUnifiedSubscription({ metadata: { orderId: '1234-5678-9012' } });
+        assert.equal(result.payment.orderId, '1234-5678-9012', 'orderId should come from metadata');
+      },
+    },
+
+    {
+      name: 'payment-order-id-null-when-missing',
+      async run({ assert }) {
+        const result = toUnifiedSubscription({});
+        assert.equal(result.payment.orderId, null, 'Missing metadata → null orderId');
+      },
+    },
+
     {
       name: 'payment-event-metadata-passed-through',
       async run({ assert }) {
@@ -432,6 +448,7 @@ module.exports = {
         assert.equal(result.trial.claimed, false, 'Empty → trial not claimed');
         assert.equal(result.cancellation.pending, false, 'Empty → not pending');
         assert.equal(result.payment.processor, 'stripe', 'Empty → still stripe');
+        assert.equal(result.payment.orderId, null, 'Empty → null orderId');
         assert.equal(result.payment.resourceId, null, 'Empty → null resourceId');
         assert.equal(result.payment.frequency, null, 'Empty → null frequency');
       },

package/test/helpers/user.js

@@ -393,6 +393,7 @@ module.exports = {
         });
 
         assert.equal(user.subscription.payment.processor, 'stripe', 'processor preserved');
+        assert.equal(user.subscription.payment.orderId, null, 'missing orderId defaults to null');
         assert.equal(user.subscription.payment.resourceId, 'sub_123', 'resourceId preserved');
         assert.equal(user.subscription.payment.frequency, null, 'missing frequency defaults to null');
         assert.ok(user.subscription.payment.startDate.timestamp, 'missing startDate gets default');

package/test/routes/payments/intent.js

@@ -126,11 +126,14 @@ module.exports = {
 
         assert.isSuccess(response, 'Should succeed with test processor');
         assert.ok(response.data.id, 'Should return intent ID');
+        assert.ok(response.data.orderId, 'Should return orderId');
+        assert.match(response.data.orderId, /^\d{4}-\d{4}-\d{4}$/, 'orderId should be XXXX-XXXX-XXXX format');
         assert.ok(response.data.url, 'Should return URL');
 
-        // Verify intent doc was saved
-        const intentDoc = await firestore.get(`payments-intents/${response.data.id}`);
+        // Verify intent doc was saved (keyed by orderId)
+        const intentDoc = await firestore.get(`payments-intents/${response.data.orderId}`);
         assert.ok(intentDoc, 'Intent doc should exist');
+        assert.equal(intentDoc.intentId, response.data.id, 'Intent ID should match response');
         assert.equal(intentDoc.processor, 'test', 'Processor should be test');
         assert.equal(intentDoc.productId, paidProduct.id, 'Product should match');
 
@@ -151,10 +154,10 @@ module.exports = {
       async run({ http, assert, config, accounts, firestore, waitFor }) {
         const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices);
         const uid = accounts.basic.uid;
-        const subDocPath = `payments-subscriptions/_test-sub-history-${uid}`;
+        const orderDocPath = `payments-orders/_test-order-history-${uid}`;
 
         // Create fake subscription history so user is ineligible for trial
-        await firestore.set(subDocPath, { uid, processor: 'test', status: 'cancelled' });
+        await firestore.set(orderDocPath, { owner: uid, type: 'subscription', processor: 'test', status: 'cancelled' });
 
         try {
           const response = await http.as('basic').post('payments/intent', {
@@ -167,8 +170,8 @@ module.exports = {
           // Should succeed (not reject with 400) — trial silently downgraded
           assert.isSuccess(response, 'Should not reject — trial silently downgraded');
 
-          // Verify intent saved with trial=false
-          const intentDoc = await firestore.get(`payments-intents/${response.data.id}`);
+          // Verify intent saved with trial=false (keyed by orderId)
+          const intentDoc = await firestore.get(`payments-intents/${response.data.orderId}`);
           assert.equal(intentDoc.trial, false, 'Trial should be false (downgraded)');
 
           // Clean up: wait for auto-webhook, restore basic user
@@ -181,7 +184,7 @@ module.exports = {
             subscription: { product: { id: 'basic' }, status: 'active' },
           }, { merge: true });
         } finally {
-          await firestore.delete(subDocPath);
+          await firestore.delete(orderDocPath);
         }
       },
     },