@dainamite/cpq-billing-connector 0.1.0

package/src/modules/cpq_billing_connector/lib/prorationHelper.ts

@@ -0,0 +1,74 @@
+/**
+ * Proration math owned by the connector.
+ *
+ * Per spec: "Connectors computing proration values should follow the
+ * same convention for consistency on the draft" — i.e. half-up 2dp,
+ * matching billing's `roundHalfUp2dp` policy. Duplicated here (vs
+ * imported from `@dainamite/billing`) on purpose so the connector
+ * doesn't reach into billing's internals via a non-peer-dep path.
+ *
+ * The formula is the linear-day proration documented in the spec's
+ * "CPQ-side payload contracts" section:
+ *   `prorationAmount = unitPrice × quantity × daysRemaining / daysInPeriod`
+ *
+ * For mid-cycle additions (e.g. customer buys an add-on on 2026-05-15
+ * for a monthly cycle anchored on the 1st), `daysRemaining` is the
+ * number of full days from the effective date through the cycle end
+ * (inclusive), and `daysInPeriod` is the cycle's calendar-day length.
+ *
+ * The CPQ event payload supplies both numbers — the connector trusts
+ * the calendar arithmetic CPQ already did (it derived the period
+ * boundaries from the subscription's lifecycle). It does NOT
+ * re-compute them from `effectiveDate` and `cycleEnd` to avoid
+ * disagreeing with CPQ's source of truth.
+ */
+
+/**
+ * Half-up 2dp rounding that survives JS floating-point edges
+ * (e.g. `1.005 * 100 === 100.49999…`). Matches billing's
+ * `roundHalfUp2dp` policy.
+ */
+function roundHalfUp2dp(value: number): number {
+  return Math.round((value + Number.EPSILON) * 100) / 100
+}
+
+export type ProrationInput = {
+  unitPrice: number
+  quantity: number
+  daysInPeriod: number
+  daysRemaining: number
+}
+
+export type ProrationResult = {
+  /** Numeric amount, half-up 2dp, suitable for `rate_json.amount`. */
+  amount: number
+  /** Computed string form for `billing.items.create.rateJson` (4dp). */
+  amountString: string
+}
+
+export function computeProration(input: ProrationInput): ProrationResult {
+  // Guard against the degenerate "0 days in period" — should never
+  // happen if CPQ derived the values, but defending here avoids a
+  // silent NaN propagation if it ever does.
+  if (input.daysInPeriod <= 0) {
+    return { amount: 0, amountString: '0.0000' }
+  }
+  const raw =
+    (input.unitPrice * input.quantity * Math.max(0, input.daysRemaining)) /
+    input.daysInPeriod
+  const rounded = roundHalfUp2dp(raw)
+  return { amount: rounded, amountString: rounded.toFixed(4) }
+}
+
+/**
+ * Helper used by subscribers to format the proration description so
+ * the resulting invoice line reads naturally (matches spec example:
+ * "Proration: Package X from 2026-05-15 to 2026-05-31").
+ */
+export function formatProrationDescription(params: {
+  productName: string
+  effectiveDate: string
+  cycleEnd: string
+}): string {
+  return `Proration: ${params.productName} from ${params.effectiveDate} to ${params.cycleEnd}`
+}

package/src/modules/cpq_billing_connector/setup.ts

@@ -0,0 +1,11 @@
+import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
+
+/**
+ * Connector has no tenant-init work to do. It ships zero entities,
+ * zero dictionaries, zero default roles. The subscribers auto-register
+ * via the generator's `subscribers/` discovery; nothing else is
+ * required for the module to function.
+ */
+export const setup: ModuleSetupConfig = {}
+
+export default setup

package/src/modules/cpq_billing_connector/subscribers/cpq-subscription-activated.ts

@@ -0,0 +1,134 @@
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { BillingApiClient, type Scope, type AccountSeed } from '../lib/billingApiClient'
+import { mapSubscriptionItemsToBillingItems } from '../lib/chargeMapper'
+import type { CpqSubscriptionItem } from '../lib/chargeMapper'
+
+/**
+ * Subscriber: `cpq.subscription.activated` → billing onboarding.
+ *
+ * `@dainamite/cpq` emits this event when a new-sale order is activated
+ * (`cpqOrderService.activateOrder`).
+ *
+ * Behaviour when fired:
+ *   1. Get-or-create the Billing Account for `(tenant, org, customerId)`.
+ *      Missing account → shell account with placeholders (operator
+ *      must configure before billing fires). `nextBillDate` defaults
+ *      to today + one month so the Bill Run won't bill an under-
+ *      configured account until the operator advances it.
+ *   2. For every charge on every CPQ subscription item, create a
+ *      Billing Item via `billing.items.create`. `source_ref` is the
+ *      deterministic `cpq-<subId>-<subItemId>-<chargeType>` key, so
+ *      re-firing the activation event hits the idempotency guard
+ *      instead of duplicating items.
+ *
+ * Errors propagate to the persistent queue worker, which retries
+ * per the OM queue contract.
+ */
+
+export const metadata = {
+  event: 'cpq.subscription.activated',
+  persistent: true,
+  id: 'cpq-billing-connector:subscription-activated',
+}
+
+type ActivatedPayload = {
+  tenantId: string
+  organizationId: string
+  subscriptionId: string
+  customerId: string
+  currencyCode: string
+  /** Optional richer customer fields — used when present, otherwise placeholders. */
+  customerName?: string
+  invoiceEmail?: string
+  invoiceLanguage?: string
+  invoiceAddress?: Record<string, unknown>
+  billCycle?: 'monthly' | 'quarterly' | 'annually' | 'weekly'
+  billCycleAnchor?: string
+  nextBillDate?: string
+  taxId?: string | null
+  items: CpqSubscriptionItem[]
+  /** Activation date — used as bill_start_date on every created item. */
+  activationDate?: string
+}
+
+function isoDateAddMonths(months: number): string {
+  // Clamp the day to the last valid day of the target month so Jan 31 + 1
+  // month → Feb 28/29 (not Mar 3, which is what `setUTCMonth` alone would
+  // produce by overflowing into the next month).
+  const d = new Date()
+  const targetYear = d.getUTCFullYear()
+  const targetMonth = d.getUTCMonth() + months
+  const lastDayOfTargetMonth = new Date(Date.UTC(targetYear, targetMonth + 1, 0)).getUTCDate()
+  d.setUTCDate(Math.min(d.getUTCDate(), lastDayOfTargetMonth))
+  d.setUTCMonth(targetMonth)
+  return d.toISOString().slice(0, 10)
+}
+
+function todayIsoDate(): string {
+  return new Date().toISOString().slice(0, 10)
+}
+
+function buildAccountSeed(payload: ActivatedPayload): AccountSeed {
+  return {
+    customerId: payload.customerId,
+    name: payload.customerName ?? `Customer ${payload.customerId}`,
+    currencyCode: payload.currencyCode,
+    billCycle: payload.billCycle ?? 'monthly',
+    billCycleAnchor: payload.billCycleAnchor ?? '1',
+    invoiceEmail:
+      payload.invoiceEmail ?? `billing+${payload.customerId}@invalid.local`,
+    invoiceLanguage: payload.invoiceLanguage ?? 'en',
+    invoiceAddress: payload.invoiceAddress ?? {
+      line1: 'TBD',
+      city: 'TBD',
+      postal_code: 'TBD',
+      country: 'XX',
+    },
+    nextBillDate: payload.nextBillDate
+      ? new Date(payload.nextBillDate)
+      : new Date(isoDateAddMonths(1)),
+    taxId: payload.taxId ?? null,
+  }
+}
+
+export default async function handle(payload: ActivatedPayload): Promise<void> {
+  if (!payload?.tenantId || !payload.organizationId || !payload.customerId) {
+    return
+  }
+  if (!payload.subscriptionId || !Array.isArray(payload.items) || payload.items.length === 0) {
+    return
+  }
+
+  const container = await createRequestContainer()
+  const billingApi = new BillingApiClient(container)
+  const scope: Scope = {
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId,
+  }
+
+  const account = await billingApi.getOrCreateAccount(scope, buildAccountSeed(payload))
+
+  const billStartDate = payload.activationDate ?? todayIsoDate()
+  const itemPayloads = mapSubscriptionItemsToBillingItems({
+    subscriptionId: payload.subscriptionId,
+    items: payload.items,
+    billStartDate,
+  })
+
+  // Bulk-create — one command for the whole subscription's charges
+  // instead of one round-trip per charge. Idempotent per source_ref,
+  // so a re-fired activation event is a no-op.
+  await billingApi.bulkCreateItems(
+    scope,
+    itemPayloads.map((item) => ({
+      billAccountId: account.id,
+      type: item.type,
+      billStartDate: item.billStartDate,
+      description: item.description,
+      rateJson: item.rateJson,
+      subscriptionId: item.subscriptionId,
+      subscriptionItemId: item.subscriptionItemId,
+      sourceRef: item.sourceRef,
+    })),
+  )
+}

package/src/modules/cpq_billing_connector/subscribers/cpq-subscription-amended.ts

@@ -0,0 +1,169 @@
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+// TODO(L2-boundary): `cycleContaining` is a runtime function imported from
+// `@dainamite/billing` internals (not a stable public surface). A breaking
+// rename or signature change in billing's `billPeriod` will manifest here
+// as a runtime crash on the first `cpq.subscription.amended` event. Same
+// trade-off as `billingApiClient.ts` — kept inline for now because the
+// proration math is non-trivial and we don't want to fork it. Promote
+// `cycleContaining` to a documented public export of @dainamite/billing
+// (or expose via a billing REST helper) before the connector hits v1.
+import { cycleContaining } from '@dainamite/billing/modules/billing/lib/billPeriod'
+import type { BillCycle } from '@dainamite/billing/modules/billing/data/validators'
+import { BillingApiClient, type Scope } from '../lib/billingApiClient'
+import {
+  mapSubscriptionItemsToBillingItems,
+  type CpqSubscriptionItem,
+} from '../lib/chargeMapper'
+import {
+  computeProration,
+  formatProrationDescription,
+} from '../lib/prorationHelper'
+
+/**
+ * Subscriber: `cpq.subscription.amended` → mid-cycle add / remove.
+ *
+ * CPQ's amended event carries `addedItems`, `removedSubscriptionItemIds`
+ * and the `effectiveDate` of the amendment. The connector:
+ *   1. Creates a Billing Item for every added charge — recurring items
+ *      start on `effectiveDate`; the engine's mid-cycle rule skips the
+ *      current cycle and bills from the next full cycle.
+ *   2. For every added RECURRING charge, posts a `one_time` proration
+ *      line covering the partial current cycle. The billing cycle is
+ *      derived HERE (not in CPQ) — proration is a billing concept, so
+ *      the connector computes it from the account's `nextBillDate` +
+ *      `billCycle` via billing's `cycleContaining`.
+ *   3. End-dates every Billing Item of each removed subscription item
+ *      at `effectiveDate - 1 day`.
+ */
+
+export const metadata = {
+  event: 'cpq.subscription.amended',
+  persistent: true,
+  id: 'cpq-billing-connector:subscription-amended',
+}
+
+type AmendedPayload = {
+  tenantId: string
+  organizationId: string
+  subscriptionId: string
+  customerId: string
+  /** YYYY-MM-DD; the date the amend takes effect mid-cycle. */
+  effectiveDate: string
+  addedItems?: CpqSubscriptionItem[]
+  removedSubscriptionItemIds?: string[]
+}
+
+const DAY_MS = 86_400_000
+
+function toMidnightMs(value: Date | string): number {
+  const d =
+    value instanceof Date
+      ? new Date(value.getTime())
+      : new Date(`${value}T00:00:00.000Z`)
+  d.setUTCHours(0, 0, 0, 0)
+  return d.getTime()
+}
+
+/** Inclusive day count from `from` through `to`. */
+function inclusiveDays(from: Date | string, to: Date | string): number {
+  return Math.round((toMidnightMs(to) - toMidnightMs(from)) / DAY_MS) + 1
+}
+
+function isoDateMinusOneDay(iso: string): string {
+  const d = new Date(`${iso}T00:00:00.000Z`)
+  d.setUTCDate(d.getUTCDate() - 1)
+  return d.toISOString().slice(0, 10)
+}
+
+export default async function handle(payload: AmendedPayload): Promise<void> {
+  if (!payload?.tenantId || !payload.organizationId) return
+  if (!payload.subscriptionId || !payload.effectiveDate) return
+
+  const added = payload.addedItems ?? []
+  const removed = payload.removedSubscriptionItemIds ?? []
+  if (added.length === 0 && removed.length === 0) return
+
+  const container = await createRequestContainer()
+  const billingApi = new BillingApiClient(container)
+  const scope: Scope = {
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId,
+  }
+
+  // Activation runs first and creates the account. If it's missing,
+  // there is nothing to amend — the queue will have retried activation.
+  const account = await billingApi.findAccountByCustomer(scope, payload.customerId)
+  if (!account) return
+
+  // 1. New Billing Items for every added charge.
+  const itemsToCreate = mapSubscriptionItemsToBillingItems({
+    subscriptionId: payload.subscriptionId,
+    items: added,
+    billStartDate: payload.effectiveDate,
+  }).map((item) => ({
+    billAccountId: account.id,
+    type: item.type,
+    billStartDate: item.billStartDate,
+    description: item.description,
+    rateJson: item.rateJson,
+    subscriptionId: item.subscriptionId,
+    subscriptionItemId: item.subscriptionItemId,
+    sourceRef: item.sourceRef,
+  }))
+
+  // 2. Mid-cycle proration. The billing cycle the amend lands in is
+  // derived from the account here — CPQ does not own the billing cycle.
+  if (added.length > 0) {
+    const period = cycleContaining(
+      account.nextBillDate,
+      account.billCycle as BillCycle,
+      payload.effectiveDate,
+    )
+    const cycleEnd = period.periodEnd.toISOString().slice(0, 10)
+    const daysInPeriod = inclusiveDays(period.periodStart, period.periodEnd)
+    const daysRemaining = inclusiveDays(payload.effectiveDate, period.periodEnd)
+
+    for (const addedItem of added) {
+      for (const charge of addedItem.charges) {
+        if (charge.type !== 'recurring' || typeof charge.unitPrice !== 'number') {
+          continue
+        }
+        const { amount } = computeProration({
+          unitPrice: charge.unitPrice,
+          quantity: addedItem.quantity,
+          daysInPeriod,
+          daysRemaining,
+        })
+        if (amount === 0) continue
+        itemsToCreate.push({
+          billAccountId: account.id,
+          type: 'one_time',
+          billStartDate: payload.effectiveDate,
+          description: formatProrationDescription({
+            productName: addedItem.productName,
+            effectiveDate: payload.effectiveDate,
+            cycleEnd,
+          }),
+          rateJson: { amount },
+          subscriptionId: payload.subscriptionId,
+          subscriptionItemId: addedItem.subscriptionItemId,
+          sourceRef: `cpq-${payload.subscriptionId}-${addedItem.subscriptionItemId}-proration-${payload.effectiveDate}`,
+        })
+      }
+    }
+  }
+
+  await billingApi.bulkCreateItems(scope, itemsToCreate)
+
+  // 3. End-date every Billing Item of each removed subscription item.
+  const endDate = isoDateMinusOneDay(payload.effectiveDate)
+  for (const removedSubItemId of removed) {
+    const items = await billingApi.findItemsBySubscriptionItem(scope, removedSubItemId)
+    for (const item of items) {
+      await billingApi.updateItem(scope, {
+        id: item.id,
+        billEndDate: endDate,
+      })
+    }
+  }
+}

package/src/modules/cpq_billing_connector/subscribers/cpq-subscription-cancelled.ts

@@ -0,0 +1,64 @@
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { BillingApiClient, type Scope } from '../lib/billingApiClient'
+
+/**
+ * Subscriber: `cpq.subscription.cancelled` → set bill_end_date on
+ * every billing item attached to the subscription.
+ *
+ * The connector uses the spec's `effectiveDate` (cancellation date)
+ * minus one day as `bill_end_date` so the engine's recurring
+ * selector stops including the item from the cycle containing the
+ * cancellation onward.
+ *
+ * Final-period proration / refund credits (per spec) are issued by
+ * CPQ — the connector does not invent them here. If a credit is
+ * needed, CPQ posts a negative `one_time` Billing Item via this
+ * same connector path (e.g. an `amend` event preceding the cancel).
+ */
+
+export const metadata = {
+  event: 'cpq.subscription.cancelled',
+  persistent: true,
+  id: 'cpq-billing-connector:subscription-cancelled',
+}
+
+type CancelledPayload = {
+  tenantId: string
+  organizationId: string
+  subscriptionId: string
+  /** YYYY-MM-DD; the date the cancellation takes effect. */
+  effectiveDate: string
+}
+
+function isoDateMinusOneDay(iso: string): string {
+  const d = new Date(`${iso}T00:00:00.000Z`)
+  d.setUTCDate(d.getUTCDate() - 1)
+  return d.toISOString().slice(0, 10)
+}
+
+export default async function handle(payload: CancelledPayload): Promise<void> {
+  if (!payload?.tenantId || !payload.organizationId) return
+  if (!payload.subscriptionId || !payload.effectiveDate) return
+
+  const container = await createRequestContainer()
+  const billingApi = new BillingApiClient(container)
+  const scope: Scope = {
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId,
+  }
+
+  const items = await billingApi.findItemsBySubscription(scope, payload.subscriptionId)
+  if (items.length === 0) return
+
+  const endDate = isoDateMinusOneDay(payload.effectiveDate)
+  for (const item of items) {
+    // Idempotency: skip if already end-dated to this exact date.
+    if (item.billEndDate && item.billEndDate.toISOString().slice(0, 10) === endDate) {
+      continue
+    }
+    await billingApi.updateItem(scope, {
+      id: item.id,
+      billEndDate: endDate,
+    })
+  }
+}

package/src/modules/cpq_billing_connector/subscribers/cpq-subscription-merged.ts

@@ -0,0 +1,56 @@
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { BillingApiClient, type Scope } from '../lib/billingApiClient'
+
+/**
+ * Subscriber: `cpq.subscription.merged` → re-link items to the
+ * merged subscription.
+ *
+ * Per the spec: "Move Billing Items from source subscriptions to
+ * the merged subscription (update `subscription_id`)." This keeps
+ * the audit trail continuous — same Billing Items, just pointing
+ * at the new subscription so any future lookup by subscription_id
+ * lands at the merged target.
+ *
+ * The source subscriptions transition to the terminal `superseded`
+ * status in CPQ; the `superseded` subscriber separately end-dates
+ * any items still pointing at the source ids (defense in depth — if
+ * a race left an item un-relinked, superseded catches it).
+ */
+
+export const metadata = {
+  event: 'cpq.subscription.merged',
+  persistent: true,
+  id: 'cpq-billing-connector:subscription-merged',
+}
+
+type MergedPayload = {
+  tenantId: string
+  organizationId: string
+  /** The new merged subscription's id (the survivor). */
+  mergedSubscriptionId: string
+  /** The source subscriptions absorbed into the merge. */
+  sourceSubscriptionIds: string[]
+}
+
+export default async function handle(payload: MergedPayload): Promise<void> {
+  if (!payload?.tenantId || !payload.organizationId) return
+  if (!payload.mergedSubscriptionId || !Array.isArray(payload.sourceSubscriptionIds)) return
+  if (payload.sourceSubscriptionIds.length === 0) return
+
+  const container = await createRequestContainer()
+  const billingApi = new BillingApiClient(container)
+  const scope: Scope = {
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId,
+  }
+
+  for (const sourceId of payload.sourceSubscriptionIds) {
+    const items = await billingApi.findItemsBySubscription(scope, sourceId)
+    for (const item of items) {
+      await billingApi.updateItem(scope, {
+        id: item.id,
+        subscriptionId: payload.mergedSubscriptionId,
+      })
+    }
+  }
+}

package/src/modules/cpq_billing_connector/subscribers/cpq-subscription-renewed.ts

@@ -0,0 +1,92 @@
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { BillingApiClient, type Scope } from '../lib/billingApiClient'
+import {
+  mapSubscriptionItemsToBillingItems,
+  type CpqSubscriptionItem,
+} from '../lib/chargeMapper'
+
+/**
+ * Subscriber: `cpq.subscription.renewed` → extend term + add items.
+ *
+ * On renewal the existing items either:
+ *   - Stay active (no `bill_end_date` set, so the engine keeps
+ *     billing them as recurring) — connector touches nothing.
+ *   - Had a previously-set `bill_end_date` (e.g. fixed-term
+ *     subscription) — connector clears or extends it to the new
+ *     term's end (`newTermEnd` from the payload).
+ *
+ * New items added at renewal (e.g. upsell at renewal time) are
+ * created with `bill_start_date = newTermStart`, same shape as
+ * activation.
+ *
+ * The connector does NOT post a proration line for renewals — by
+ * definition renewal happens at the cycle boundary (or it's an early
+ * renewal, which the integrator should issue as `amend` + `renew`
+ * via the spec's ARC flow rather than this single event).
+ */
+
+export const metadata = {
+  event: 'cpq.subscription.renewed',
+  persistent: true,
+  id: 'cpq-billing-connector:subscription-renewed',
+}
+
+type RenewedPayload = {
+  tenantId: string
+  organizationId: string
+  subscriptionId: string
+  customerId: string
+  newTermStart: string
+  newTermEnd?: string | null
+  addedItems?: CpqSubscriptionItem[]
+}
+
+export default async function handle(payload: RenewedPayload): Promise<void> {
+  if (!payload?.tenantId || !payload.organizationId) return
+  if (!payload.subscriptionId || !payload.newTermStart) return
+
+  const container = await createRequestContainer()
+  const billingApi = new BillingApiClient(container)
+  const scope: Scope = {
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId,
+  }
+
+  const existingItems = await billingApi.findItemsBySubscription(scope, payload.subscriptionId)
+
+  // Extend the bill_end_date on items that had one. Items without
+  // an end date are open-ended; nothing to do.
+  for (const item of existingItems) {
+    if (!item.billEndDate) continue
+    await billingApi.updateItem(scope, {
+      id: item.id,
+      billEndDate: payload.newTermEnd ?? null,
+    })
+  }
+
+  // Add new items at the renewal boundary.
+  const accountId =
+    existingItems[0]?.billAccountId ??
+    (await billingApi.findAccountByCustomer(scope, payload.customerId))?.id ??
+    null
+  if (!accountId) return
+
+  const newPayloads = mapSubscriptionItemsToBillingItems({
+    subscriptionId: payload.subscriptionId,
+    items: payload.addedItems ?? [],
+    billStartDate: payload.newTermStart,
+  })
+  await billingApi.bulkCreateItems(
+    scope,
+    newPayloads.map((item) => ({
+      billAccountId: accountId,
+      type: item.type,
+      billStartDate: item.billStartDate,
+      description: item.description,
+      rateJson: item.rateJson,
+      subscriptionId: item.subscriptionId,
+      subscriptionItemId: item.subscriptionItemId,
+      sourceRef: item.sourceRef,
+    })),
+  )
+}

package/src/modules/cpq_billing_connector/subscribers/cpq-subscription-superseded.ts

@@ -0,0 +1,66 @@
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { BillingApiClient, type Scope } from '../lib/billingApiClient'
+
+/**
+ * Subscriber: `cpq.subscription.superseded` → end-date items still
+ * pointing at a superseded source.
+ *
+ * Per the spec's XD-250 ARC notes, merge-renewal produces a brand
+ * new subscription (the "merge target") and transitions the source
+ * subscriptions to `superseded`. The `merged` subscriber already
+ * re-links Billing Items to the target — this subscriber is the
+ * defense-in-depth net: if any items remain attached to the
+ * superseded source (re-link missed them, race, manual fix-up),
+ * end-date them at the supersession effective date so the engine
+ * stops billing them.
+ *
+ * In the steady-state "no race" path, this subscriber finds zero
+ * items and is a no-op — which is fine.
+ */
+
+export const metadata = {
+  event: 'cpq.subscription.superseded',
+  persistent: true,
+  id: 'cpq-billing-connector:subscription-superseded',
+}
+
+type SupersededPayload = {
+  tenantId: string
+  organizationId: string
+  /** The id that is being superseded (the OLD subscription). */
+  subscriptionId: string
+  /** YYYY-MM-DD; when the supersession took effect. */
+  effectiveDate: string
+}
+
+function isoDateMinusOneDay(iso: string): string {
+  const d = new Date(`${iso}T00:00:00.000Z`)
+  d.setUTCDate(d.getUTCDate() - 1)
+  return d.toISOString().slice(0, 10)
+}
+
+export default async function handle(payload: SupersededPayload): Promise<void> {
+  if (!payload?.tenantId || !payload.organizationId) return
+  if (!payload.subscriptionId || !payload.effectiveDate) return
+
+  const container = await createRequestContainer()
+  const billingApi = new BillingApiClient(container)
+  const scope: Scope = {
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId,
+  }
+
+  const stragglers = await billingApi.findItemsBySubscription(scope, payload.subscriptionId)
+  if (stragglers.length === 0) return
+
+  const endDate = isoDateMinusOneDay(payload.effectiveDate)
+  for (const item of stragglers) {
+    if (item.billEndDate && item.billEndDate.toISOString().slice(0, 10) === endDate) {
+      continue
+    }
+    await billingApi.updateItem(scope, {
+      id: item.id,
+      billEndDate: endDate,
+    })
+  }
+}