tapimo 0.15.0 → 0.18.0

package/src/apps/management/Billing.test.ts

@@ -1,5 +1,5 @@
 import { nanoid } from 'nanoid'
-import type Stripe from 'stripe'
+import Stripe from 'stripe'
 
 import * as Runtime from '../../../test/runtime.js'
 import * as ApiKeys from '../../ApiKeys.js'
@@ -33,16 +33,23 @@ const input = {
 /** Inserts and finalizes one billable row; `seed` derives a unique sign payload. */
 async function finalized(
   db: Db.Db,
-  options: { feeAmount: string; orgId?: string; seed: string },
+  options: {
+    chainId?: number
+    feeAmount: string
+    finalizedAt?: string
+    orgId?: string
+    seed: string
+  },
 ): Promise<SponsoredTransactions.Record> {
   const row = await SponsoredTransactions.upsert(db, {
     ...input,
+    ...(options.chainId === undefined ? {} : { chainId: options.chainId }),
     ...(options.orgId ? { orgId: options.orgId } : {}),
     signPayload: `0x${options.seed.repeat(32)}`,
   })
   await SponsoredTransactions.finalize(db, row.id, {
     feeAmount: options.feeAmount,
-    finalizedAt: new Date().toISOString(),
+    finalizedAt: options.finalizedAt ?? new Date().toISOString(),
   })
   return row
 }
@@ -178,6 +185,7 @@ type StubSubscription = {
  * item/subscription creation are captured for assertions.
  */
 function stubStripe(options: {
+  createdAt?: number | undefined
   meterEvent?: ((params: { identifier: string }) => void) | undefined
   subscriptions?: readonly StubSubscription[] | undefined
   subscriptionsList?: (() => Promise<void>) | undefined
@@ -239,7 +247,7 @@ function stubStripe(options: {
     subscriptionItems: {
       create: async (params: { price: string; subscription: string }) => {
         itemsCreated.push(params)
-        return { created: Math.floor(Date.now() / 1_000) }
+        return { created: options.createdAt ?? Math.floor(Date.now() / 1_000) }
       },
     },
     subscriptions: {
@@ -248,7 +256,7 @@ function stubStripe(options: {
         return {
           items: {
             data: params.items.map(({ price }) => ({
-              created: Math.floor(Date.now() / 1_000),
+              created: options.createdAt ?? Math.floor(Date.now() / 1_000),
               price: { id: price },
             })),
           },
@@ -315,6 +323,89 @@ describe('status', () => {
 })
 
 describe('createReporter', () => {
+  test('retries an explicitly rejected Stripe event after its configuration is corrected', async () => {
+    const db = create()
+    await db.migrate()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+    const row = await finalized(db, { feeAmount: '100000', seed: '42' })
+    let reject = true
+    const { meterEvents, stripe } = stubStripe({
+      meterEvent: () => {
+        if (reject)
+          throw new Stripe.errors.StripeInvalidRequestError({
+            message: 'Meter configuration is invalid.',
+            statusCode: 400,
+            type: 'invalid_request_error',
+          })
+      },
+      subscriptions: [{ items: ['feePayerSpend', 'apiRequests'], status: 'active' }],
+    })
+    const reporter = Billing.createReporter({ db, stripe })
+    expect(await reporter.tick()).toStrictEqual({ failed: 1, reported: 0, skipped: 0 })
+    expect((await SponsoredTransactions.get(db, row.id))?.meterEventFirstAttemptedAt).toBeNull()
+
+    reject = false
+    expect(await reporter.tick()).toStrictEqual({ failed: 0, reported: 1, skipped: 0 })
+    expect(meterEvents.map(({ identifier }) => identifier)).toStrictEqual([row.id])
+    await db.close()
+  })
+
+  test('stops an uncertain Stripe resend after its identifier window', async () => {
+    const db = create()
+    await db.migrate()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+    const row = await finalized(db, { feeAmount: '100000', seed: '41' })
+    await SponsoredTransactions.beginMeterEvent(
+      db,
+      row.id,
+      new Date(Date.now() - 24 * 60 * 60 * 1_000).toISOString(),
+    )
+
+    const { meterEvents, stripe } = stubStripe({
+      subscriptions: [{ items: ['feePayerSpend', 'apiRequests'], status: 'active' }],
+    })
+    expect(await Billing.createReporter({ db, stripe }).tick()).toStrictEqual({
+      failed: 1,
+      reported: 0,
+      skipped: 0,
+    })
+    expect(meterEvents).toHaveLength(0)
+    expect((await SponsoredTransactions.get(db, row.id))?.meterReportedAt).toBeNull()
+    await db.close()
+  })
+
+  test('rotates unavailable sponsorships behind healthy rows', async () => {
+    const db = create()
+    await db.migrate()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+    const unavailable = await finalized(db, {
+      feeAmount: '100000',
+      finalizedAt: '2026-01-01T00:00:00.000Z',
+      orgId: 'org_missing',
+      seed: '39',
+    })
+    const healthy = await finalized(db, {
+      chainId: 421700099,
+      feeAmount: '250000',
+      finalizedAt: '2026-01-02T00:00:00.000Z',
+      seed: '40',
+    })
+
+    const { meterEvents, stripe } = stubStripe({
+      subscriptions: [{ items: ['feePayerSpend', 'apiRequests'], status: 'active' }],
+    })
+    const reporter = Billing.createReporter({ batchSize: 1, db, stripe })
+    expect(await reporter.tick()).toStrictEqual({ failed: 1, reported: 0, skipped: 0 })
+    expect(await reporter.tick()).toStrictEqual({ failed: 0, reported: 1, skipped: 0 })
+    expect(await reporter.tick()).toStrictEqual({ failed: 1, reported: 0, skipped: 0 })
+    expect(meterEvents.map(({ identifier }) => identifier)).toStrictEqual([healthy.id])
+    expect(
+      (await SponsoredTransactions.get(db, unavailable.id))?.meterEventFirstAttemptedAt,
+    ).toBeNull()
+    expect((await SponsoredTransactions.get(db, unavailable.id))?.meterReportedAt).toBeNull()
+    await db.close()
+  })
+
   test('behavior: a poisoned row never stalls the queue', async () => {
     const db = create()
     await db.migrate()
@@ -387,6 +478,7 @@ describe('createReporter', () => {
       skipped: 0,
     })
     expect((await SponsoredTransactions.get(db, row.id))?.meterReportedAt).not.toBeNull()
+    expect((await SponsoredTransactions.get(db, row.id))?.meterEventFirstAttemptedAt).not.toBeNull()
     expect(await Billing.createReporter({ db, stripe }).tick()).toStrictEqual({
       failed: 0,
       reported: 0,
@@ -395,24 +487,35 @@ describe('createReporter', () => {
     await db.close()
   })
 
-  test('behavior: canceled customers skip without meter events', async () => {
-    const db = create()
-    await db.migrate()
-    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
-    await StripeCustomers.setStatus(db, 'org_1', 'canceled')
-    const row = await finalized(db, { feeAmount: '100000', seed: '03' })
-
-    const { meterEvents, stripe } = stubStripe({ subscriptions: [{ status: 'active' }] })
-    expect(await Billing.createReporter({ db, stripe }).tick()).toStrictEqual({
-      failed: 0,
-      reported: 0,
-      skipped: 1,
-    })
-    expect(meterEvents).toHaveLength(0)
-    // Skipped rows still mark: nobody remains to invoice, ever.
-    expect((await SponsoredTransactions.get(db, row.id))?.meterReportedAt).not.toBeNull()
-    await db.close()
-  })
+  test.each(['canceled', 'missing'] as const)(
+    'behavior: retains sponsorship liability for %s customers',
+    async (status) => {
+      const db = create()
+      await db.migrate()
+      if (status === 'canceled') {
+        await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+        await StripeCustomers.setStatus(db, 'org_1', 'canceled')
+      }
+      const row = await finalized(db, { feeAmount: '100000', seed: '03' })
+
+      // No provider call is needed until a billing identity is available.
+      const stripe = new Stripe('sk_test_unavailable_customer', { maxNetworkRetries: 0 })
+      const reporter = Billing.createReporter({ db, stripe })
+      expect(await reporter.tick()).toStrictEqual({
+        failed: 1,
+        reported: 0,
+        skipped: 0,
+      })
+      expect((await SponsoredTransactions.get(db, row.id))?.meterReportedAt).toBeNull()
+      expect(await reporter.tick()).toStrictEqual({ failed: 1, reported: 0, skipped: 0 })
+      expect(
+        (await SponsoredTransactions.listUnreported(db, { chainIds: [Viem.chainId.mainnet] })).map(
+          ({ id }) => id,
+        ),
+      ).toEqual([row.id])
+      await db.close()
+    },
+  )
 
   test('behavior: ensures the metered subscription once and stamps its backlog at now', async () => {
     const db = create()
@@ -779,7 +882,8 @@ describe('createRequestUsageReporter', () => {
 
     // Tick 1: fresh customer, initial seal of 5. The just-created item bills at
     // now (no backdate).
-    const first = stubStripe({ subscriptions: [] })
+    const createdAt = Math.floor(now() / 1_000)
+    const first = stubStripe({ createdAt, subscriptions: [] })
     const reporter1 = Billing.createRequestUsageReporter({
       db,
       now,
@@ -788,9 +892,9 @@ describe('createRequestUsageReporter', () => {
     })
     expect(await reporter1.tick()).toStrictEqual({ failed: 0, reported: 1, skipped: 0 })
     expect(first.meterEvents).toEqual([
-      { event_name: 'api_request_count', identifier: expect.any(String), payload: expect.objectContaining({ value: '5' }) }, // prettier-ignore
+      { event_name: 'api_request_count', identifier: expect.any(String), payload: expect.objectContaining({ value: '5' }), timestamp: createdAt }, // prettier-ignore
     ])
-    expect(first.meterEvents[0]!.timestamp).toBeUndefined()
+    expect(first.meterEvents[0]!.timestamp).toBe(createdAt)
     expect((await RequestUsage.getBucket(db, { bucketStart, environment: 'production', orgId: 'org_1' }))?.reportedCount).toBe(5) // prettier-ignore
 
     // Tick 2: count grows to 8; only the delta of 3 bills, backdated (item exists).
@@ -824,6 +928,30 @@ describe('createRequestUsageReporter', () => {
     await db.close()
   })
 
+  test('behavior: clamps initial backlog to an item provisioned by another reporter', async () => {
+    const db = create()
+    await db.migrate()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+    await StripeCustomers.setStatus(db, 'org_1', 'active')
+    const createdAt = Math.floor(Date.parse('2026-01-01T18:00:00.000Z') / 1_000)
+    const { meterEvents, stripe } = stubStripe({
+      subscriptions: [
+        { createdAt, items: ['feePayerSpend', 'routeSubsidy', 'apiRequests'], status: 'active' },
+      ],
+    })
+
+    expect(
+      await Billing.createRequestUsageReporter({
+        db,
+        now,
+        readCounts: async () => [{ bucketStart, count: 5, orgId: 'org_1' }],
+        stripe,
+      }).tick(),
+    ).toStrictEqual({ failed: 0, reported: 1, skipped: 0 })
+    expect(meterEvents[0]?.timestamp).toBe(createdAt)
+    await db.close()
+  })
+
   test('behavior: overlapping ticks cannot claim the same observed watermark twice', async () => {
     const db = create()
     await db.migrate()
@@ -941,6 +1069,7 @@ describe('createRequestUsageReporter', () => {
       bucketStart,
       deltaCount: 6,
       environment: 'production',
+      eventTimestamp: bucketStart,
       identifier: 'rq_production_deadbeef0001_0_0',
       orgId: 'org_1',
       sequence: 0,
@@ -969,11 +1098,12 @@ describe('createRequestUsageReporter', () => {
     await db.migrate()
     await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
     await StripeCustomers.setStatus(db, 'org_1', 'active')
+    const createdAt = Math.floor(Date.parse('2026-01-01T18:00:00.000Z') / 1_000)
     const { stripe } = stubStripe({
       meterEvent() {
         throw new Error('Stripe unavailable')
       },
-      subscriptions: [{ items: ['feePayerSpend', 'apiRequests'], status: 'active' }],
+      subscriptions: [{ createdAt, items: ['feePayerSpend', 'apiRequests'], status: 'active' }],
     })
     const reporter = Billing.createRequestUsageReporter({
       db,
@@ -990,6 +1120,102 @@ describe('createRequestUsageReporter', () => {
         oldestPendingAgeSeconds: expect.any(Number),
       },
     ])
+
+    const pending = (await RequestUsage.listPending(db, 'production'))[0]!
+    await db.kysely
+      .updateTable('request_usage_meter_events')
+      .set({ eventTimestamp: pending.firstAttemptedAt })
+      .where('identifier', '=', pending.identifier)
+      .execute()
+    const retryAt = new Date(pending.firstAttemptedAt).getTime() + 23 * 60 * 60 * 1_000
+    const failedRetry = stubStripe({ subscriptions: [] })
+    expect(
+      await Billing.createRequestUsageReporter({
+        db,
+        now: () => retryAt,
+        readCounts: async () => [],
+        stripe: failedRetry.stripe,
+      }).tick(),
+    ).toStrictEqual({ failed: 1, reported: 0, skipped: 0 })
+    expect(failedRetry.meterEvents).toHaveLength(0)
+    expect(await RequestUsage.listPending(db, 'production')).toHaveLength(1)
+    expect(await reporter.pending()).toMatchObject([{ count: 1, environment: 'production' }])
+
+    const retry = stubStripe({ subscriptions: [] })
+    expect(
+      await Billing.createRequestUsageReporter({
+        db,
+        now: () => retryAt + 24 * 60 * 60 * 1_000,
+        readCounts: async () => [],
+        stripe: retry.stripe,
+      }).tick(),
+    ).toStrictEqual({ failed: 1, reported: 0, skipped: 0 })
+    expect(retry.meterEvents).toHaveLength(0)
+    await db.close()
+  })
+
+  test('behavior: stops retrying a legacy event after identifier uniqueness expires', async () => {
+    const db = create()
+    await db.migrate()
+    await RequestUsage.insertPending(db, {
+      bucketStart,
+      deltaCount: 6,
+      environment: 'production',
+      eventTimestamp: new Date().toISOString(),
+      identifier: 'rq_production_deadbeef0003_0_0',
+      orgId: 'org_1',
+      sequence: 0,
+      stripeCustomerId: 'cus_1',
+    })
+    await db.kysely
+      .updateTable('request_usage_meter_events')
+      .set({ eventTimestamp: null })
+      .where('identifier', '=', 'rq_production_deadbeef0003_0_0')
+      .execute()
+    const pending = (await RequestUsage.listPending(db, 'production'))[0]!
+    expect(pending).not.toHaveProperty('eventTimestamp')
+    const stripe = stubStripe({ subscriptions: [] })
+    expect(
+      await Billing.createRequestUsageReporter({
+        db,
+        now: () => new Date(pending.firstAttemptedAt).getTime() + 23 * 60 * 60 * 1_000,
+        readCounts: async () => [],
+        stripe: stripe.stripe,
+      }).tick(),
+    ).toStrictEqual({ failed: 1, reported: 0, skipped: 0 })
+    expect(stripe.meterEvents).toHaveLength(0)
+    expect(await RequestUsage.listPending(db, 'production')).toHaveLength(1)
+    await db.close()
+  })
+
+  test('behavior: settles a retry when Stripe confirms the identifier already exists', async () => {
+    const db = create()
+    await db.migrate()
+    await RequestUsage.insertPending(db, {
+      bucketStart,
+      deltaCount: 6,
+      environment: 'production',
+      eventTimestamp: bucketStart,
+      identifier: 'rq_production_deadbeef0002_0_0',
+      orgId: 'org_1',
+      sequence: 0,
+      stripeCustomerId: 'cus_1',
+    })
+    const { stripe } = stubStripe({
+      meterEvent({ identifier }) {
+        throw new Error(`An event already exists with identifier ${identifier}.`)
+      },
+      subscriptions: [],
+    })
+    expect(
+      await Billing.createRequestUsageReporter({
+        db,
+        now,
+        readCounts: async () => [],
+        stripe,
+      }).tick(),
+    ).toStrictEqual({ failed: 0, reported: 1, skipped: 0 })
+    expect((await RequestUsage.getBucket(db, { bucketStart, environment: 'production', orgId: 'org_1' }))?.reportedCount).toBe(6) // prettier-ignore
     await db.close()
   })
 })

package/src/apps/management/Billing.ts

@@ -13,7 +13,6 @@ import type * as Scope from '../../Scope.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import type * as Store from '../../internal/Store.js'
 import * as StripeCustomers from '../../db/tables/stripeCustomers.js'
-import * as Viem from '../../internal/Viem.js'
 
 /**
  * Whether the organization has any active billing source — the production
@@ -449,12 +448,18 @@ export class DuplicateSubscriptionError extends Error {
   }
 }
 
+/** Safe Stripe meter-event ingestion window below its documented 35-day limit. */
+const meterEventIngestionWindowMs = 34 * 24 * 60 * 60 * 1_000
+
+/** Safe retry window below Stripe's documented 24-hour identifier uniqueness period. */
+const meterEventRetryWindowMs = 23 * 60 * 60 * 1_000
+
 /**
  * Creates the sponsorship and Route Subsidy metering job. Each tick reports
  * finalized usage, then marks each row after Stripe acknowledges it.
  */
 export function createReporter(options: createReporter.Options): createReporter.Reporter {
-  const { batchSize = 100, chainIds = [Viem.chainId.mainnet], db, stripe } = options
+  const { batchSize = 100, db, stripe } = options
   return {
     async tick() {
       // Resolve per tick so Workers factories build a fresh Hyperdrive-pooled
@@ -462,7 +467,10 @@ export function createReporter(options: createReporter.Options): createReporter.
       const database = Db.get(db)
       const [depositSubsidies, sponsorships, transferSubsidies] = await Promise.all([
         RoutesDeposits.listUnreportedSubsidies(database, { limit: batchSize }),
-        SponsoredTransactions.listUnreported(database, { chainIds, limit: batchSize }),
+        SponsoredTransactions.claimUnreported(database, {
+          attemptedAt: new Date().toISOString(),
+          limit: batchSize,
+        }),
         RoutesTransfers.listUnreportedSubsidies(database, { limit: batchSize }),
       ])
       const rows: UsageRow[] = [
@@ -532,7 +540,7 @@ export function createReporter(options: createReporter.Options): createReporter.
             // just-created meter item bills nothing before its start, so
             // its backlog stamps at now too.
             const finalizedAt = new Date(row.finalizedAt!).getTime()
-            const recent = Date.now() - finalizedAt < 34 * 24 * 60 * 60 * 1000
+            const recent = Date.now() - finalizedAt < meterEventIngestionWindowMs
             const item = subscription.items[kind]
             const stamp =
               recent && item !== undefined && !item.created && finalizedAt >= item.createdAt * 1_000
@@ -540,6 +548,19 @@ export function createReporter(options: createReporter.Options): createReporter.
             meteredAt = new Date(
               (timestamp ?? Math.floor(Date.now() / 1_000)) * 1_000,
             ).toISOString()
+            if (row.source === 'sponsorship') {
+              const firstAttemptedAt = await SponsoredTransactions.beginMeterEvent(
+                database,
+                row.id,
+                new Date().toISOString(),
+              )
+              // Stripe only deduplicates identifiers for 24 hours. An older
+              // uncertain acknowledgment requires reconciliation before resend.
+              if (Date.now() - new Date(firstAttemptedAt).getTime() >= meterEventRetryWindowMs)
+                throw new Error(
+                  `Stripe acknowledgement is ambiguous after the safe meter-event retry window for ${row.id}`,
+                )
+            }
             // The row id makes short-window retries idempotent on Stripe's
             // side; `meter_reported_at` is the durable exactly-once guard.
             try {
@@ -556,7 +577,20 @@ export function createReporter(options: createReporter.Options): createReporter.
             } catch (error) {
               // Stripe may persist the event before the Worker records its ack.
               // Its duplicate response proves this exact row was already metered.
-              if (!isDuplicateMeterEvent(error, row.id)) throw error
+              if (!isDuplicateMeterEvent(error, row.id)) {
+                // An explicit client error rejects this submission. Only
+                // uncertain outcomes retain the first-send retry clock.
+                if (
+                  row.source === 'sponsorship' &&
+                  error instanceof Stripe.errors.StripeError &&
+                  error.statusCode !== undefined &&
+                  error.statusCode >= 400 &&
+                  error.statusCode < 500 &&
+                  error.statusCode !== 409
+                )
+                  await SponsoredTransactions.clearRejectedMeterEventAttempt(database, row.id)
+                throw error
+              }
             }
             reported++
           } else if (row.source === 'routes-deposit' && row.orgId.startsWith('key_')) {
@@ -564,16 +598,11 @@ export function createReporter(options: createReporter.Options): createReporter.
             // Stripe customer. Provider subsidies on those routes are non-billable.
             meteredAt = new Date().toISOString()
             skipped++
-          } else if (row.source !== 'sponsorship') {
-            // Production Routes subsidies were authorized against active billing.
-            // Keep the liability durable if that customer disappears before reporting.
-            throw new Error(`Stripe customer unavailable for Routes subsidy ${row.id}`)
           } else {
-            // Deleted orgs and Stripe-deleted (canceled) customers keep their
-            // ledger rows; nobody remains to invoice.
-            skipped++
+            // Missing billing identity cannot discharge a committed liability; preserve it for retry and alert through the scheduled-task failure counter.
+            throw new Error(`Stripe customer unavailable for ${row.source} ${row.id}`)
           }
-          // Mark only after the Stripe ack (or a definitive no-customer skip).
+          // Mark only after the Stripe ack or the non-billable one-off-key exemption.
           const reportedAt = new Date().toISOString()
           if (row.source !== 'sponsorship') {
             if (!meteredAt) throw new Error(`Routes subsidy ${row.id} has no meter timestamp`)
@@ -635,10 +664,8 @@ function isDuplicateMeterEvent(error: unknown, identifier: string): boolean {
 export declare namespace createReporter {
   /** Options for {@link createReporter}. */
   type Options = {
-    /** Maximum rows reported per source per tick. @default 100 */
+    /** Maximum rows attempted per source per tick. @default 100 */
     batchSize?: number | undefined
-    /** Chains whose spend is metered. @default mainnet */
-    chainIds?: readonly number[] | undefined
     /** Database holding sponsorship rows, or a factory resolved per tick (Workers/Hyperdrive). */
     db: Db.Source
     /** Stripe client used to send meter events. */
@@ -647,7 +674,7 @@ export declare namespace createReporter {
 
   /** A scheduled metering job. */
   type Reporter = {
-    /** Runs one reporting pass. Failed rows stay unmarked and retry next tick. */
+    /** Runs one reporting pass. Failed rows stay unmarked and retry on later ticks. */
     tick(): Promise<{ failed: number; reported: number; skipped: number }>
   }
 }
@@ -729,14 +756,36 @@ export function createRequestUsageReporter(
         const blocked = new Set<string>()
         for (const event of await RequestUsage.listPending(database, environment)) {
           try {
-            await client.billing.meterEvents.create({
-              event_name: meters.apiRequests.eventName,
-              identifier: event.identifier,
-              payload: {
-                stripe_customer_id: event.stripeCustomerId,
-                value: String(event.deltaCount),
-              },
-            })
+            const eventTimestamp = event.eventTimestamp
+            if (
+              nowMs - new Date(event.firstAttemptedAt).getTime() >= meterEventRetryWindowMs ||
+              (eventTimestamp !== undefined &&
+                nowMs - new Date(eventTimestamp).getTime() >= meterEventIngestionWindowMs)
+            ) {
+              failed++
+              blocked.add(bucketKey(event.orgId, event.bucketStart))
+              await RequestUsage.markError(
+                database,
+                event.identifier,
+                'Stripe acknowledgement is ambiguous after the safe meter-event retry window.',
+              )
+              continue
+            }
+            try {
+              await client.billing.meterEvents.create({
+                event_name: meters.apiRequests.eventName,
+                identifier: event.identifier,
+                payload: {
+                  stripe_customer_id: event.stripeCustomerId,
+                  value: String(event.deltaCount),
+                },
+                ...(eventTimestamp === undefined
+                  ? {}
+                  : { timestamp: Math.floor(new Date(eventTimestamp).getTime() / 1_000) }),
+              })
+            } catch (error) {
+              if (!isDuplicateMeterEvent(error, event.identifier)) throw error
+            }
             if (await RequestUsage.settle(database, event.identifier, new Date().toISOString()))
               reported++
           } catch (error) {
@@ -781,9 +830,17 @@ export function createRequestUsageReporter(
             // The observed watermark is stable for every tick claiming this delta.
             const sequence = watermark?.reportedCount ?? 0
             const identifier = usageIdentifier(environment, orgId, bucketStart, sequence)
+            const item = subscription.items.apiRequests
+            if (!item) throw new Error(`API request meter item unavailable for ${orgId}`)
+            // Meter events before the subscription item's creation are accepted
+            // but not invoiced, so clamp backlog to its billing eligibility window.
+            const eventTimestamp = new Date(
+              Math.max(new Date(bucketStart).getTime(), item.createdAt * 1_000),
+            ).toISOString()
             const inserted = await RequestUsage.insertPending(database, {
               ...key,
               deltaCount: delta,
+              eventTimestamp,
               identifier,
               sequence,
               stripeCustomerId: customer.stripeCustomerId,
@@ -791,14 +848,11 @@ export function createRequestUsageReporter(
             // A concurrent tick already claimed this delta; leave it to that run.
             if (!inserted) continue
 
-            // Backdate to the bucket hour unless the item was just created (it
-            // bills nothing before its start, so its backlog stamps at now).
-            const stamp = !subscription.items.apiRequests?.created
             await client.billing.meterEvents.create({
               event_name: meters.apiRequests.eventName,
               identifier,
               payload: { stripe_customer_id: customer.stripeCustomerId, value: String(delta) },
-              ...(stamp ? { timestamp: Math.floor(new Date(bucketStart).getTime() / 1000) } : {}),
+              timestamp: Math.floor(new Date(eventTimestamp).getTime() / 1_000),
             })
             if (await RequestUsage.settle(database, identifier, new Date().toISOString()))
               reported++

package/src/apps/management/routes/api-keys.test.ts

@@ -1010,7 +1010,7 @@ describe('keys', () => {
       {
         "error": {
           "code": "api_key_forbidden",
-          "message": "API key missing required scope",
+          "message": "API key is missing required permissions: data:read. Use an API key with these scopes.",
         },
       }
     `)