@dainamite/billing 0.20.0 → 0.21.0

package/src/modules/billing/api/invoices/route.ts

@@ -1,61 +1,53 @@
 import { NextResponse } from 'next/server'
 import type { EntityManager } from '@mikro-orm/postgresql'
-import { z } from 'zod'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { billingInvoiceListQuerySchema } from '../../data/validators'
+import { daysOverdueSql, isoDay, overdueSql } from '../../lib/overdue'
 
 /**
- * `GET /api/billing/invoices`
+ * `GET /api/billing/invoices` — paginated list of billing documents
+ * (Spec 0: billing-owned `billing_invoices`, never core `sales`).
  *
- * Lists `core/sales` invoices that the billing engine emitted (i.e.
- * carry `metadata.bill_run_id`). Hand-rolled rather than wrapped via
- * `makeCrudRoute` because the filter predicate is a JSONB
- * `metadata->>'bill_run_id' IS NOT NULL` check that doesn't map
- * cleanly onto the factory's `where`-shaped filter API, and the
- * entity itself is owned by `core/sales` — keeping the surface
- * read-only and hand-rolled avoids surprising the cross-module
- * reviewer.
+ * Filters (all on indexed columns): `status`, `documentType`, `billRunId`,
+ * `billAccountId`, `testRun` (`true` / `false`), `id`, `search` (number).
+ * Spec B: `overdue=true` (computed, B-D6 — see `lib/overdue.ts`), `dueFrom` /
+ * `dueTo` (due-date window). Each row carries `bill_account_name` (joined)
+ * and `days_overdue` (0 when not overdue).
  *
- * Filters:
- *   - `status` — draft / posted / paid / void
- *   - `billRunId` — exact match on `metadata->>'bill_run_id'`
- *   - `billAccountId` — exact match on `metadata->>'bill_account_id'`
- *   - `testRun=true|false` — flips the `metadata->>'test_run'` filter
- *   - `search` — substring on invoice_number
- *
- * Sort: started_at DESC (most recent first). Pagination: standard
- * page / pageSize (capped at 100).
+ * Hand-written SQL instead of the CRUD factory: documents are written by the
+ * bill-run engine without query-index side effects, so the factory's
+ * query-engine path would not see them. Sort: `created_at DESC`.
  */
 
 export const metadata = {
   GET: { requireAuth: true, requireFeatures: ['billing.invoice.view'] },
 }
 
-const querySchema = z
-  .object({
-    page: z.coerce.number().int().min(1).default(1),
-    pageSize: z.coerce.number().int().min(1).max(100).default(50),
-    status: z.enum(['draft', 'posted', 'paid', 'void']).optional(),
-    billRunId: z.string().uuid().optional(),
-    billAccountId: z.string().uuid().optional(),
-    testRun: z.coerce.boolean().optional(),
-    search: z.string().optional(),
-  })
-  .passthrough()
-
 type BillingInvoiceRow = {
   id: string
-  invoice_number: string
-  status: string | null
-  currency_code: string
+  number: string
+  document_type: string
+  status: string
+  test_run: boolean
+  bill_account_id: string
+  bill_account_name: string | null
+  bill_run_id: string | null
+  bill_date: string | null
+  period_start: string | null
+  period_end: string | null
   issue_date: string | null
   due_date: string | null
-  subtotal_net_amount: string
-  grand_total_net_amount: string
-  grand_total_gross_amount: string
-  paid_total_amount: string
-  outstanding_amount: string
-  metadata: Record<string, unknown> | null
+  currency_code: string
+  subtotal_net: string
+  tax_total: string
+  total_gross: string
+  paid_total: string
+  credited_total: string
+  outstanding: string
+  days_overdue: number
+  corrects_invoice_id: string | null
+  topup_id: string | null
   created_at: string
   updated_at: string
 }
@@ -76,67 +68,67 @@ export async function GET(req: Request) {
     }
 
     const url = new URL(req.url)
-    const query = querySchema.parse(
-      Object.fromEntries(url.searchParams.entries()),
-    )
+    const query = billingInvoiceListQuerySchema.parse(Object.fromEntries(url.searchParams.entries()))
 
     const em = (container.resolve('em') as EntityManager).fork()
 
-    // Build the predicate. `jsonb_exists(metadata, 'bill_run_id')` is
-    // the function form of the JSONB `?` "key exists" operator — the
-    // operator form cannot be used here because `em.execute` treats a
-    // literal `?` as a positional parameter placeholder. Keeps us
-    // narrow to billing-managed invoices, never bleeding into invoices
-    // written by other modules.
-    const whereClauses: string[] = [
-      'tenant_id = ?',
-      'organization_id = ?',
-      'deleted_at IS NULL',
-      "jsonb_exists(metadata, 'bill_run_id')",
-    ]
+    const whereClauses: string[] = ['i.tenant_id = ?', 'i.organization_id = ?', 'i.deleted_at IS NULL']
     const params: unknown[] = [auth.tenantId, organizationId]
-
-    if (query.status) {
-      whereClauses.push('status = ?')
-      params.push(query.status)
+    const filters: Array<[unknown, string]> = [
+      [query.id, 'i.id = ?'],
+      [query.status, 'i.status = ?'],
+      [query.documentType, 'i.document_type = ?'],
+      [query.billRunId, 'i.bill_run_id = ?'],
+      [query.billAccountId, 'i.bill_account_id = ?'],
+      [query.testRun, 'i.test_run = ?'],
+    ]
+    for (const [value, clause] of filters) {
+      if (value === undefined || value === null || value === '') continue
+      whereClauses.push(clause)
+      params.push(value)
     }
-    if (query.billRunId) {
-      whereClauses.push("metadata->>'bill_run_id' = ?")
-      params.push(query.billRunId)
+    const today = isoDay(new Date())
+    if (query.overdue === true) {
+      whereClauses.push(overdueSql('i'))
+      params.push(today)
+    } else if (query.overdue === false) {
+      whereClauses.push(`NOT COALESCE(${overdueSql("i")}, false)`)
+      params.push(today)
     }
-    if (query.billAccountId) {
-      whereClauses.push("metadata->>'bill_account_id' = ?")
-      params.push(query.billAccountId)
+    if (query.dueFrom) {
+      whereClauses.push('i.due_date >= ?::date')
+      params.push(query.dueFrom)
     }
-    if (typeof query.testRun === 'boolean') {
-      if (query.testRun) {
-        whereClauses.push("metadata->>'test_run' = 'true'")
-      } else {
-        whereClauses.push("(metadata->>'test_run' IS NULL OR metadata->>'test_run' != 'true')")
-      }
+    if (query.dueTo) {
+      whereClauses.push('i.due_date <= ?::date')
+      params.push(query.dueTo)
     }
-    if (typeof query.search === 'string' && query.search.trim()) {
-      whereClauses.push('invoice_number ILIKE ?')
-      params.push(`%${query.search.trim().replace(/[%_]/g, (m) => `\\${m}`)}%`)
+    if (query.search) {
+      whereClauses.push('i.number ILIKE ?')
+      params.push(`%${query.search.replace(/[%_\\]/g, (m) => `\\${m}`)}%`)
     }
 
     const whereSql = whereClauses.join(' AND ')
     const countRows = (await em.execute(
-      `SELECT COUNT(*)::int AS total FROM sales_invoices WHERE ${whereSql}`,
+      `SELECT COUNT(*)::int AS total FROM billing_invoices i WHERE ${whereSql}`,
       params,
     )) as unknown as Array<{ total: number }>
     const total = countRows?.[0]?.total ?? 0
 
     const offset = (query.page - 1) * query.pageSize
     const itemRows = (await em.execute(
-      `SELECT id, invoice_number, status, currency_code, issue_date, due_date,
-              subtotal_net_amount, grand_total_net_amount, grand_total_gross_amount,
-              paid_total_amount, outstanding_amount, metadata, created_at, updated_at
-       FROM sales_invoices
+      `SELECT i.id, i.number, i.document_type, i.status, i.test_run, i.bill_account_id,
+              a.name AS bill_account_name, i.bill_run_id, i.bill_date, i.period_start, i.period_end,
+              i.issue_date, i.due_date, i.currency_code, i.subtotal_net, i.tax_total, i.total_gross,
+              i.paid_total, i.credited_total, i.outstanding, i.corrects_invoice_id, i.corrects_invoice_number, i.topup_id,
+              ${daysOverdueSql('i')}::int AS days_overdue,
+              i.created_at, i.updated_at
+       FROM billing_invoices i
+       LEFT JOIN billing_accounts a ON a.id = i.bill_account_id AND a.tenant_id = i.tenant_id
        WHERE ${whereSql}
-       ORDER BY created_at DESC
+       ORDER BY i.created_at DESC
        LIMIT ? OFFSET ?`,
-      [...params, query.pageSize, offset],
+      [today, today, ...params, query.pageSize, offset],
     )) as unknown as BillingInvoiceRow[]
 
     return NextResponse.json({
@@ -156,12 +148,15 @@ export const openApi = {
   methods: {
     GET: {
       tags: ['Billing'],
-      summary: 'List billing-managed invoices',
+      summary: 'List billing documents',
       description:
-        'Returns a paginated list of `core/sales` invoices that the ' +
-        'billing engine emitted (matched via `metadata->>\'bill_run_id\'` ' +
-        'presence). Supports status / billRunId / billAccountId / testRun ' +
-        '/ invoice_number search filters.',
+        'Paginated billing documents (invoices, credit / debit memos, top-up receipts) from ' +
+        '`billing_invoices`. Filters: status, documentType, billRunId, billAccountId, testRun ' +
+        '(`true`/`false`), id, number search, `overdue` (`true`/`false` — posted or partially paid, ' +
+        'past due, outstanding > 0), `dueFrom` / `dueTo` (YYYY-MM-DD). Each row adds `days_overdue`. ' +
+        'Fields use billing names: `number`, `document_type`, ' +
+        '`total_gross`, `outstanding`, `bill_date`, `period_start/end`, `bill_account_name`, … ' +
+        '(0.21.0 renamed them from the core-sales names — see MIGRATION.md).',
     },
   },
 }

package/src/modules/billing/api/items/bulk/route.ts

@@ -87,6 +87,7 @@ export const openApi = createBillingCrudOpenApi({
       'Idempotent per `sourceRef` (one batched existence check). ' +
       'Returns `{ created, deduplicated, items: [{ sourceRef, id, ' +
       'deduplicated }] }`. Always HTTP 200 — duplicates are reported ' +
-      'in the body, never an error.',
+      'in the body, never an error. Entries accept `chargeTiming` / `prorate` ' +
+      '(recurring only; defaults `in_advance` / true).',
   },
 })

package/src/modules/billing/api/items/change-price/route.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod'
+import { runCommandRoute } from '../../../lib/commandRoute'
+
+/**
+ * `POST /api/billing/items/change-price` — change a recurring item's price
+ * from a date on: the item ends the day before `effectiveDate` and a copy with
+ * `unitPrice` starts on it (same account, description, timing, proration,
+ * VAT, price basis, references and end date). Returns both item ids.
+ */
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.item.manage'] },
+}
+
+const bodySchema = z.object({
+  id: z.string().uuid(),
+  effectiveDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+  unitPrice: z.coerce.number().finite().nonnegative(),
+})
+
+const responseSchema = z.object({ previousItemId: z.string().uuid(), newItemId: z.string().uuid() })
+
+export async function POST(req: Request) {
+  return runCommandRoute(req, {
+    commandId: 'billing.items.change_price',
+    bodySchema,
+    resourceKind: 'billing.item',
+    resourceId: (body) => body.id,
+    logLabel: 'billing/items/change-price.POST',
+  })
+}
+
+export const openApi = {
+  methods: {
+    POST: {
+      tags: ['Billing'],
+      summary: "Change a recurring item's price from a date",
+      description:
+        'Ends the item the day before `effectiveDate` and creates a copy with the new `unitPrice` (on the item price basis) ' +
+        'starting on `effectiveDate`. Already-billed days after the change are credited / re-charged by the Bill Run per the ' +
+        "item's proration setting, so nothing is billed twice.",
+      requestBody: { schema: bodySchema },
+      responses: [{ status: 200, description: 'Both item ids', schema: responseSchema }],
+      errors: [
+        { status: 404, description: 'Item not found' },
+        {
+          status: 422,
+          description:
+            '`billing.item.price_change_recurring_only` / `_inactive` / `_before_start` (must be after the start date) / `_after_end`',
+        },
+      ],
+    },
+  },
+}

package/src/modules/billing/api/items/route.ts

@@ -33,6 +33,9 @@ const billingItemListItemSchema = z.object({
   id: z.string().uuid(),
   bill_account_id: z.string().uuid(),
   bill_account_name: z.string().nullable(),
+  /** Spec F (F2): the owning account's currency and mode, for the form. */
+  bill_account_currency: z.string().nullable(),
+  bill_account_mode: z.enum(['postpaid', 'prepaid']).nullable(),
   type: z.string(),
   bill_start_date: z.string(),
   bill_end_date: z.string().nullable(),
@@ -44,6 +47,10 @@ const billingItemListItemSchema = z.object({
   source_ref: z.string().nullable(),
   currency_mismatch: z.boolean(),
   billed_to_date: z.string().nullable(),
+  charge_timing: z.enum(['in_advance', 'in_arrears']),
+  prorate: z.boolean(),
+  tax_rate: z.union([z.string(), z.number()]),
+  price_basis: z.enum(['net', 'gross']),
   is_active: z.boolean(),
   organization_id: z.string().uuid(),
   tenant_id: z.string().uuid(),
@@ -87,6 +94,10 @@ const crud = makeCrudRoute({
       'source_ref',
       'currency_mismatch',
       'billed_to_date',
+      'charge_timing',
+      'prorate',
+      'tax_rate',
+      'price_basis',
       'is_active',
       'organization_id',
       'tenant_id',
@@ -196,7 +207,7 @@ const crud = makeCrudRoute({
   },
   hooks: {
     // Items reference their account by FK id only; the list + detail UI
-    // wants the human-readable account name. One bounded query
+    // wants the account name, currency and mode. One bounded query
     // (≤ pageSize ids) resolves it after the page is fetched.
     afterList: async (payload: unknown, ctx: unknown) => {
       const items = ((payload as { items?: unknown[] } | null)?.items ?? []) as Array<
@@ -212,11 +223,12 @@ const crud = makeCrudRoute({
       if (accountIds.length === 0) return
       const em = (ctx as { container: AwilixContainer }).container.resolve<EntityManager>('em')
       const accounts = await em.find(BillingAccount, { id: { $in: accountIds } })
-      const nameById = new Map(
-        accounts.map((a) => [String(a.id), a.name] as [string, unknown]),
-      )
+      const byId = new Map(accounts.map((a) => [String(a.id), a] as const))
       for (const row of items) {
-        row.bill_account_name = nameById.get(String(row.bill_account_id)) ?? null
+        const account = byId.get(String(row.bill_account_id))
+        row.bill_account_name = account?.name ?? null
+        row.bill_account_currency = account?.currencyCode ?? null
+        row.bill_account_mode = account?.billingMode ?? null
       }
     },
   },
@@ -238,14 +250,18 @@ export const openApi = createBillingCrudOpenApi({
       'Creates a billing item. Idempotent via `sourceRef`: re-POSTing the same ' +
       '`(tenantId, billAccountId, sourceRef)` returns the existing row with ' +
       '`deduplicated: true` instead of creating a duplicate. The unique index ' +
-      'on `(tenant_id, bill_account_id, source_ref)` is the correctness gate.',
+      'on `(tenant_id, bill_account_id, source_ref)` is the correctness gate. ' +
+      'Recurring items accept `chargeTiming` (`in_advance` default | `in_arrears`) and ' +
+      '`prorate` (default true); other types reject non-default values (400).',
   },
   update: {
     schema: billingItemUpdateSchema,
     responseSchema: defaultOkResponseSchema,
     description:
       'Updates a billing item. `type` and `sourceRef` are immutable — to change ' +
-      'either, soft-delete the item and create a new one.',
+      'either, soft-delete the item and create a new one. `chargeTiming` / `prorate` ' +
+      'may change at any time on recurring items — billing resumes from `billed_to_date`, ' +
+      'so no day is billed twice.',
   },
   del: {
     schema: z.object({ id: z.string().uuid() }),

package/src/modules/billing/api/payment-imports/[id]/route.ts

@@ -0,0 +1,49 @@
+import { NextResponse } from 'next/server'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import {
+  organizationScopeRequiredResponse,
+  resolveActiveOrganizationId,
+} from '@open-mercato/shared/lib/auth/organizationScope'
+
+/** `GET /api/billing/payment-imports/[id]` — one upload batch with its row errors (Spec C). */
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['billing.payment.view'] },
+}
+
+export async function GET(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  try {
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    if (!auth || !auth.tenantId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    const organizationId = resolveActiveOrganizationId(auth)
+    if (!organizationId) return organizationScopeRequiredResponse()
+    const { id } = await params
+    const em = (container.resolve('em') as EntityManager).fork()
+    const rows = (await em.execute(
+      `SELECT id, file_name, row_count, counts, errors, user_id, created_at
+         FROM billing_payment_imports
+        WHERE id = ? AND tenant_id = ? AND organization_id = ? AND deleted_at IS NULL`,
+      [id, auth.tenantId, organizationId],
+    )) as unknown as Array<Record<string, unknown>>
+    if (!rows?.length) return NextResponse.json({ error: 'Import not found' }, { status: 404 })
+    return NextResponse.json({ import: rows[0] })
+  } catch (err) {
+    console.error('[billing/payment-imports/[id].GET]', err)
+    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
+  }
+}
+
+export const openApi = {
+  methods: {
+    GET: {
+      tags: ['Billing'],
+      summary: 'Get a payment import batch',
+      description: 'Counts per outcome and the row errors (line number + message, capped at 200).',
+      responses: [{ status: 200, description: '`{ import }`' }],
+      errors: [{ status: 404, description: 'Import not found' }],
+    },
+  },
+}

package/src/modules/billing/api/payment-imports/route.ts

@@ -0,0 +1,57 @@
+import { NextResponse } from 'next/server'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import {
+  organizationScopeRequiredResponse,
+  resolveActiveOrganizationId,
+} from '@open-mercato/shared/lib/auth/organizationScope'
+import { buildQueryParams } from '@open-mercato/shared/lib/crud/query-params'
+import { billingPaymentImportListQuerySchema } from '../../data/validators'
+
+/** `GET /api/billing/payment-imports` — CSV upload batches, newest first (Spec C, C-D4). */
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['billing.payment.view'] },
+}
+
+export async function GET(req: Request) {
+  try {
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    if (!auth || !auth.tenantId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    const organizationId = resolveActiveOrganizationId(auth)
+    if (!organizationId) return organizationScopeRequiredResponse()
+    const query = billingPaymentImportListQuerySchema.parse(buildQueryParams(new URL(req.url).searchParams))
+    const em = (container.resolve('em') as EntityManager).fork()
+    const where = ['tenant_id = ?', 'organization_id = ?', 'deleted_at IS NULL']
+    const params: unknown[] = [auth.tenantId, organizationId]
+    if (query.id) {
+      where.push('id = ?')
+      params.push(query.id)
+    }
+    const totalRows = (await em.execute(`SELECT COUNT(*)::int AS total FROM billing_payment_imports WHERE ${where.join(' AND ')}`, params)) as unknown as Array<{ total: number }>
+    const total = totalRows?.[0]?.total ?? 0
+    const items = await em.execute(
+      `SELECT id, file_name, row_count, counts, user_id, created_at
+         FROM billing_payment_imports WHERE ${where.join(' AND ')}
+        ORDER BY created_at DESC LIMIT ? OFFSET ?`,
+      [...params, query.pageSize, (query.page - 1) * query.pageSize],
+    )
+    return NextResponse.json({ items, total, page: query.page, pageSize: query.pageSize, totalPages: total === 0 ? 1 : Math.ceil(total / query.pageSize) })
+  } catch (err) {
+    console.error('[billing/payment-imports.GET]', err)
+    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
+  }
+}
+
+export const openApi = {
+  methods: {
+    GET: {
+      tags: ['Billing'],
+      summary: 'List payment import batches',
+      description: 'CSV uploads with counts per outcome (allocated, partially_allocated, matched, unmatched, duplicate, rejected).',
+      query: billingPaymentImportListQuerySchema,
+    },
+  },
+}

package/src/modules/billing/api/payments/[id]/route.ts

@@ -0,0 +1,63 @@
+import { NextResponse } from 'next/server'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import {
+  organizationScopeRequiredResponse,
+  resolveActiveOrganizationId,
+} from '@open-mercato/shared/lib/auth/organizationScope'
+
+/**
+ * `GET /api/billing/payments/[id]` — one payment with its active
+ * allocations (invoice number, amount, who / how allocated) — Spec C.
+ */
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['billing.payment.view'] },
+}
+
+export async function GET(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  try {
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    if (!auth || !auth.tenantId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    const organizationId = resolveActiveOrganizationId(auth)
+    if (!organizationId) return organizationScopeRequiredResponse()
+    const { id } = await params
+    const em = (container.resolve('em') as EntityManager).fork()
+    const rows = (await em.execute(
+      `SELECT p.*, a.name AS bill_account_name, a.billing_mode AS bill_account_mode
+         FROM billing_payments p
+         LEFT JOIN billing_accounts a ON a.id = p.bill_account_id AND a.tenant_id = p.tenant_id
+        WHERE p.id = ? AND p.tenant_id = ? AND p.organization_id = ? AND p.deleted_at IS NULL`,
+      [id, auth.tenantId, organizationId],
+    )) as unknown as Array<Record<string, unknown>>
+    if (!rows?.length) return NextResponse.json({ error: 'Payment not found' }, { status: 404 })
+    const allocations = await em.execute(
+      `SELECT al.id, al.invoice_id, i.number AS invoice_number, i.document_type, i.status AS invoice_status,
+              al.amount, al.currency_code, al.allocated_by, al.user_id, al.created_at
+         FROM billing_allocations al
+         LEFT JOIN billing_invoices i ON i.id = al.invoice_id
+        WHERE al.source_type = 'payment' AND al.source_id = ? AND al.tenant_id = ? AND al.organization_id = ?
+          AND al.deleted_at IS NULL
+        ORDER BY al.created_at ASC`,
+      [id, auth.tenantId, organizationId],
+    )
+    return NextResponse.json({ payment: rows[0], allocations })
+  } catch (err) {
+    console.error('[billing/payments/[id].GET]', err)
+    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
+  }
+}
+
+export const openApi = {
+  methods: {
+    GET: {
+      tags: ['Billing'],
+      summary: 'Get a billing payment',
+      description: 'The payment (incl. match reason, account, top-up link) and its active allocations.',
+      responses: [{ status: 200, description: '`{ payment, allocations[] }`' }],
+      errors: [{ status: 404, description: 'Payment not found in this organization' }],
+    },
+  },
+}

package/src/modules/billing/api/payments/allocate/route.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod'
+import { runCommandRoute } from '../../../lib/commandRoute'
+
+/** `POST /api/billing/payments/allocate` — allocate a payment to invoices (Spec C). */
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.payment.manage'] },
+}
+
+const bodySchema = z.object({ paymentId: z.string().uuid(), allocations: z.array(z.object({ invoiceId: z.string().uuid(), amount: z.coerce.number().positive() })).min(1).max(100) })
+
+export async function POST(req: Request) {
+  return runCommandRoute(req, {
+    commandId: 'billing.payments.allocate',
+    bodySchema,
+    resourceKind: 'billing.payment',
+    resourceId: (body) => body.paymentId,
+    logLabel: 'billing/payments/allocate.POST',
+  })
+}
+
+export const openApi = {
+  methods: {
+    POST: {
+      tags: ['Billing'],
+      summary: 'Allocate a payment to invoices',
+      description: 'Allocates amounts of a payment to open invoices / debit memos of its account. Invoice paid / outstanding / status are recomputed from allocations.',
+      requestBody: { schema: bodySchema },
+      responses: [{ status: 200, description: 'Updated payment state' }],
+      errors: [
+        { status: 409, description: '`billing.allocation.exceeds_outstanding` / `insufficient_unallocated` / `account_mismatch` / `currency_mismatch` / `invoice_not_open`' },
+      ],
+    },
+  },
+}

package/src/modules/billing/api/payments/assign/route.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod'
+import { runCommandRoute } from '../../../lib/commandRoute'
+
+/** `POST /api/billing/payments/assign` — assign a payment to a billing account (Spec C). */
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.payment.manage'] },
+}
+
+const bodySchema = z.object({ paymentId: z.string().uuid(), billAccountId: z.string().uuid() })
+
+export async function POST(req: Request) {
+  return runCommandRoute(req, {
+    commandId: 'billing.payments.assign',
+    bodySchema,
+    resourceKind: 'billing.payment',
+    resourceId: (body) => body.paymentId,
+    logLabel: 'billing/payments/assign.POST',
+  })
+}
+
+export const openApi = {
+  methods: {
+    POST: {
+      tags: ['Billing'],
+      summary: 'Assign a payment to a billing account',
+      description: 'Assigns an unmatched payment to a postpaid account (status → matched) and applies it as credit to the account\'s open invoices, oldest due first.',
+      requestBody: { schema: bodySchema },
+      responses: [{ status: 200, description: 'Updated payment state' }],
+      errors: [
+        { status: 404, description: 'Payment or account not found' },
+        { status: 409, description: '`billing.payment.not_unmatched` / `prepaid_account` / `currency_mismatch`' },
+      ],
+    },
+  },
+}

package/src/modules/billing/api/payments/convert-to-topup/route.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod'
+import { runCommandRoute } from '../../../lib/commandRoute'
+
+/** `POST /api/billing/payments/convert-to-topup` — convert a payment into a prepaid top-up (Spec C). */
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.payment.manage', 'billing.topup.create'] },
+}
+
+const bodySchema = z.object({ paymentId: z.string().uuid(), billAccountId: z.string().uuid() })
+
+export async function POST(req: Request) {
+  return runCommandRoute(req, {
+    commandId: 'billing.payments.convert_to_topup',
+    bodySchema,
+    resourceKind: 'billing.payment',
+    resourceId: (body) => body.paymentId,
+    logLabel: 'billing/payments/convert-to-topup.POST',
+  })
+}
+
+export const openApi = {
+  methods: {
+    POST: {
+      tags: ['Billing'],
+      summary: 'Convert a payment into a prepaid top-up',
+      description: 'Turns an unmatched payment into a captured top-up of a prepaid account (balance credit, transaction and VAT receipt). Terminal; idempotent per payment.',
+      requestBody: { schema: bodySchema },
+      responses: [{ status: 200, description: 'Updated payment state' }],
+      errors: [
+        { status: 409, description: '`billing.payment.not_prepaid` / `currency_mismatch` / `not_convertible`' },
+      ],
+    },
+  },
+}