@saasicat/spec 1.0.0-rc.23 → 1.0.0-rc.25

package/admin-api.openapi.yaml

@@ -29,7 +29,7 @@ openapi: 3.1.0
 
 info:
     title: SaaS Platform SuperAdmin API
-    version: 1.0.0-rc.23
+    version: 1.0.0-rc.25
     description: |
         Read and write operations for platform administration:
         tenants, users, subscriptions, promo codes, audit log,
@@ -352,11 +352,7 @@ paths:
                             properties:
                                 planId: { type: string }
                                 billingCycle: { type: string, enum: [MONTHLY, YEARLY] }
-                                customLimits:
-                                    type: object
-                                    additionalProperties:
-                                        type: integer
-                                        description: 'quotaKey → maxValue (-1 = unlimited)'
+                                customLimits: { $ref: '#/components/schemas/CustomLimits' }
                                 customMonthlyNet: { type: number, format: decimal }
                                 isPilot: { type: boolean }
                                 pilotEndsAt: { type: string, format: date-time }
@@ -391,6 +387,201 @@ paths:
                 '404':
                     description: No tenant with this slug (`TENANT_NOT_FOUND`)
 
+    /tenants/{slug}/subscriber:
+        parameters:
+            - $ref: '#/components/parameters/TenantSlug'
+        get:
+            tags: [subscriptions]
+            summary: The tenant's subscriber, its tax details and what holds its next contract back
+            description: >-
+                Served where the platform keeps subscribers and shows tenants
+                (`adminResources`); the manifest announces it as
+                `subscribers.read`. The standing is computed when it is read,
+                and only where a tax adapter decides; elsewhere `readiness` is
+                null.
+            responses:
+                '200':
+                    description: The subscriber, or none
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/AdminTenantSubscriber' }
+                '404':
+                    description: No tenant with this slug (`TENANT_NOT_FOUND`)
+
+    /tenants/{slug}/subscriber/history:
+        parameters:
+            - $ref: '#/components/parameters/TenantSlug'
+        get:
+            tags: [subscriptions]
+            summary: Every correction, change of country or business status, and check of the subscriber, the latest first
+            description: >-
+                Served beside `/tenants/{slug}/subscriber`; the manifest
+                announces it as `subscribers.correct`. A correction that gives
+                another VAT number is named once, as the correction it was. Empty
+                for a tenant without a subscriber.
+            responses:
+                '200':
+                    description: The history
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [entries]
+                                properties:
+                                    entries:
+                                        type: array
+                                        items:
+                                            $ref: '#/components/schemas/AdminSubscriberHistoryEntry'
+                '404':
+                    description: No tenant with this slug (`TENANT_NOT_FOUND`)
+
+    /tenants/{slug}/subscriber/identity:
+        parameters:
+            - $ref: '#/components/parameters/TenantSlug'
+        post:
+            tags: [subscriptions]
+            summary: Correct the legal identity of the tenant's subscriber
+            description: >-
+                A correction of the same legal entity — a field left out keeps
+                its value, `null` clears a tax identifier — recorded with the
+                values it replaced, the reason and who made it. `kind` is the
+                operator's declaration: a takeover by another entity is refused
+                (`SUBSCRIBER_TAKEOVER_IS_A_TRANSFER`). Where a tax adapter
+                decides and the correction gives another VAT number, that
+                number is checked right after and the check recorded, whatever
+                it found; the answer says how it went.
+            x-mfa-required: true
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [kind, reason]
+                            properties:
+                                kind: { type: string, enum: [correction, takeover] }
+                                legalName: { type: string }
+                                vatId: { type: string, nullable: true }
+                                taxNumber: { type: string, nullable: true }
+                                reason: { type: string, maxLength: 500 }
+            responses:
+                '200':
+                    description: The subscriber as it now stands, and the check its new number got
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/AdminSubscriberCorrected' }
+                '404':
+                    description: No tenant with this slug (`TENANT_NOT_FOUND`)
+                '409':
+                    description: The tenant has no subscriber (`SUBSCRIBER_REQUIRED`)
+                '422':
+                    description: >-
+                        A takeover, no reason, or a correction that changes
+                        nothing (`SUBSCRIBER_TAKEOVER_IS_A_TRANSFER`,
+                        `SUBSCRIBER_CORRECTION_REASON_REQUIRED`,
+                        `SUBSCRIBER_CORRECTION_CHANGES_NOTHING`)
+
+    /tenants/{slug}/subscriber/business-status:
+        parameters:
+            - $ref: '#/components/parameters/TenantSlug'
+        post:
+            tags: [subscriptions]
+            summary: Record whether the tenant's subscriber acts as a business, and why
+            description: >-
+                Recorded as a change of the tax origin with its reason and who
+                made it; it applies from the next contract. Setting the status it
+                has records nothing.
+            x-mfa-required: true
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [business, reason]
+                            properties:
+                                business: { type: boolean, nullable: true }
+                                reason: { type: string, maxLength: 500 }
+            responses:
+                '200':
+                    description: The subscriber as it now stands
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/AdminSubscriberCorrected' }
+                '404':
+                    description: No tenant with this slug (`TENANT_NOT_FOUND`)
+                '409':
+                    description: The tenant has no subscriber (`SUBSCRIBER_REQUIRED`)
+                '422':
+                    description: No reason (`SUBSCRIBER_BUSINESS_STATUS_REASON_REQUIRED`)
+
+    /tenants/{slug}/subscriber/vat-id-check:
+        parameters:
+            - $ref: '#/components/parameters/TenantSlug'
+        post:
+            tags: [subscriptions]
+            summary: Check the VAT number the tenant's subscriber holds, again
+            description: >-
+                Asks the service the tax adapter names and records a completed
+                check, valid or not; a check that does not complete records
+                nothing and says why. No second factor: nothing is entered, and
+                the answer is the service's.
+            responses:
+                '200':
+                    description: The subscriber as it now stands, and what the check found
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/AdminSubscriberCorrected' }
+                '404':
+                    description: No tenant with this slug (`TENANT_NOT_FOUND`)
+                '409':
+                    description: >-
+                        The tenant has no subscriber, or no tax adapter names a
+                        service (`SUBSCRIBER_REQUIRED`, `TAX_VAT_ID_CHECK_NOT_AVAILABLE`)
+                '422':
+                    description: The subscriber holds no VAT number (`SUBSCRIBER_VAT_ID_MISSING`)
+
+    /subscribers/attention:
+        get:
+            tags: [subscriptions]
+            summary: Which of these tenants hold their subscriber back from its next contract
+            description: >-
+                Served beside `/tenants/{slug}/subscriber`; the manifest
+                announces `subscribers.attention` only where a tax adapter
+                decides, and without one the answer is always empty. A tenant
+                whose subscriber is ready, and one without a subscriber, are
+                left out.
+            parameters:
+                - name: tenantId
+                  in: query
+                  description: The tenants of the page shown; repeat the parameter for each.
+                  schema:
+                      type: array
+                      maxItems: 200
+                      items: { type: string, minLength: 1 }
+                  style: form
+                  explode: true
+            responses:
+                '200':
+                    description: The tenants held back, each with why
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [attention]
+                                properties:
+                                    attention:
+                                        type: array
+                                        items:
+                                            type: object
+                                            required: [tenantId, readiness]
+                                            properties:
+                                                tenantId: { type: string }
+                                                readiness:
+                                                    $ref: '#/components/schemas/SubscriberReadiness'
+                '400':
+                    description: More than 200 tenants, or an empty tenant id
+
     # ────────────────────────────────────────────────────────
     # Users
     # ────────────────────────────────────────────────────────
@@ -816,8 +1007,9 @@ paths:
                                         id: { type: string }
                                         tenant:
                                             type: object
-                                            required: [slug, name]
+                                            required: [id, slug, name]
                                             properties:
+                                                id: { type: string }
                                                 slug: { type: string }
                                                 name: { type: string }
                                         plan: { type: string }
@@ -1000,7 +1192,7 @@ paths:
         parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
         post:
             tags: [catalog]
-            summary: Retire a plan version (endsAt; without a successor version)
+            summary: End a plan version's sale (endsAt; without a successor version)
             x-mfa-required: true
             requestBody:
                 required: true
@@ -1014,6 +1206,154 @@ paths:
                     }
             responses: { '200': { description: Terminated } }
 
+    # ── Retiring a version for running subscriptions (packages/nest/src/billing/version-retirement*) ──
+    #
+    # Served where the manifest carries the capability `planVersions.retire`. The
+    # subscriptions on a version no longer on sale move to a replacement on sale, each at
+    # the first end of a term at least three calendar months after the announcement, and
+    # may cancel without notice until then. Where the operator's terms are not confirmed to
+    # allow it, both routes refuse with `RETIREMENT_TERMS_NOT_CONFIRMED` before reading anything.
+
+    /catalog/plan-versions/{id}/retirement:
+        parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
+        get:
+            tags: [catalog]
+            summary: What retiring the version for its running subscriptions would do now
+            parameters:
+                - name: replacement
+                  in: query
+                  required: true
+                  description: The plan version the subscriptions continue on
+                  schema: { type: string, format: uuid }
+            responses:
+                '200':
+                    description: >-
+                        Whom it reaches and when, whom it does not and why, and every blocker the
+                        announcement would refuse with
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/RetirementPreview' }
+                '404':
+                    description: Either version does not exist (`PLAN_VERSION_NOT_FOUND`)
+                '422':
+                    description: >-
+                        The terms are not confirmed (`RETIREMENT_TERMS_NOT_CONFIRMED`), or the
+                        replacement is the version itself (`RETIREMENT_REPLACEMENT_IS_RETIRED`)
+        post:
+            tags: [catalog]
+            summary: Announce the retirement to every subscription it reaches
+            description: >-
+                The announcement and one notice per subscription are recorded in one
+                transaction, then handed to the application's `SubscriptionNoticePort`; a notice
+                that cannot be sent now is sent by the next run. Audited as PLAN_VERSION_RETIRE.
+            x-mfa-required: true
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema: { $ref: '#/components/schemas/RetirementAnnouncement' }
+            responses:
+                '201':
+                    description: Announced
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/RetirementAnnounced' }
+                '409':
+                    description: >-
+                        The subscriptions it reaches are no longer the ones named
+                        (`RETIREMENT_PREVIEW_CHANGED`); the body carries the preview as it stands
+                '422':
+                    description: >-
+                        The first blocker the preview reports (`RETIREMENT_*`), with every blocker
+                        beside it
+
+    /catalog/version-retirements:
+        get:
+            tags: [catalog]
+            summary: Every retirement announced, the most recent first
+            responses:
+                '200':
+                    description: List
+                    content:
+                        application/json:
+                            schema:
+                                type: array
+                                items: { $ref: '#/components/schemas/VersionRetirement' }
+
+    # Served where the manifest carries the capability `bundleVersions.retire`. The bookings
+    # on an add-on version no longer on sale continue on a version of the same add-on on
+    # sale, each at the first end of its own period at least three calendar months after
+    # its notice reached the subscriber, and may be cancelled without their minimum term
+    # until then. Where the operator's terms are not confirmed to allow it, both routes
+    # refuse with `RETIREMENT_TERMS_NOT_CONFIRMED` before reading anything.
+
+    /catalog/bundle-versions/{id}/retirement:
+        parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
+        get:
+            tags: [catalog]
+            summary: What retiring the add-on version for its running bookings would do now
+            parameters:
+                - name: replacement
+                  in: query
+                  required: true
+                  description: The version of the same add-on the bookings continue on
+                  schema: { type: string, format: uuid }
+            responses:
+                '200':
+                    description: >-
+                        Which bookings it reaches and when, which it does not and why, and every
+                        blocker the announcement would refuse with
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/BundleRetirementPreview' }
+                '404':
+                    description: Either version does not exist (`BUNDLE_VERSION_NOT_FOUND`)
+                '422':
+                    description: >-
+                        The terms are not confirmed (`RETIREMENT_TERMS_NOT_CONFIRMED`), or the
+                        replacement is the version itself (`RETIREMENT_REPLACEMENT_IS_RETIRED`)
+        post:
+            tags: [catalog]
+            summary: Announce the add-on retirement to every booking it reaches
+            description: >-
+                The announcement and one notice per booking are recorded in one transaction,
+                then handed to the application's `SubscriptionNoticePort` as
+                `bundle-version-retired`; a notice that cannot be sent now is sent by the next
+                run. Audited as BUNDLE_VERSION_RETIRE.
+            x-mfa-required: true
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema: { $ref: '#/components/schemas/BundleRetirementAnnouncement' }
+            responses:
+                '201':
+                    description: Announced
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/BundleRetirementAnnounced' }
+                '409':
+                    description: >-
+                        The bookings it reaches are no longer the ones named
+                        (`RETIREMENT_PREVIEW_CHANGED`); the body carries the preview as it stands
+                '422':
+                    description: >-
+                        The first blocker the preview reports (`BUNDLE_RETIREMENT_*`,
+                        `RETIREMENT_WITHIN_TWELVE_MONTHS`), with every blocker beside it
+
+    /catalog/bundle-version-retirements:
+        get:
+            tags: [catalog]
+            summary: Every add-on retirement announced, the most recent first
+            responses:
+                '200':
+                    description: List, each with how far it has come over the bookings it reached
+                    content:
+                        application/json:
+                            schema:
+                                type: array
+                                items: { $ref: '#/components/schemas/BundleVersionRetirement' }
+
     # ── Bundles ──
     /catalog/bundles:
         get:
@@ -1925,6 +2265,270 @@ components:
             properties:
                 endsAt: { type: string, description: 'ISO-8601; must lie in the future' }
 
+        RetiredVersionRef:
+            type: object
+            required: [planVersionId, planKey, version]
+            properties:
+                planVersionId: { type: string }
+                planKey: { type: string }
+                version: { type: integer }
+
+        RetirementSide:
+            description: 'A version as the subscribers compare it; a price of null is a rhythm it is not sold in'
+            allOf:
+                - $ref: '#/components/schemas/RetiredVersionRef'
+                - type: object
+                  required: [features, quotas, monthlyNet, yearlyNet, validUntil, endsAt]
+                  properties:
+                      features: { type: array, items: { type: string } }
+                      quotas: { type: object, additionalProperties: { type: number } }
+                      monthlyNet: { type: [number, 'null'] }
+                      yearlyNet: { type: [number, 'null'] }
+                      validUntil: { type: [string, 'null'] }
+                      endsAt: { type: [string, 'null'] }
+
+        RetirementPreview:
+            type: object
+            required: [retired, replacement, changes, asOf, reached, skipped, blockers]
+            properties:
+                retired: { $ref: '#/components/schemas/RetirementSide' }
+                replacement: { $ref: '#/components/schemas/RetirementSide' }
+                changes:
+                    type: array
+                    description: 'Every difference, retired to replacement, as the catalogue diff states it'
+                    items: { type: object }
+                asOf: { type: string, description: 'ISO-8601: the moment it is computed for' }
+                reached:
+                    type: array
+                    items:
+                        type: object
+                        required:
+                            [
+                                tenantId,
+                                subscriptionId,
+                                status,
+                                billingCycle,
+                                effectiveAt,
+                                lastDayToCancel,
+                                reachedRecently,
+                            ]
+                        properties:
+                            tenantId: { type: string }
+                            subscriptionId: { type: string }
+                            status: { type: string }
+                            billingCycle: { type: string }
+                            effectiveAt: { type: string, description: 'ISO-8601: a term end' }
+                            lastDayToCancel:
+                                { type: string, description: 'ISO date, UTC: the day before' }
+                            reachedRecently:
+                                {
+                                    type: boolean,
+                                    description: 'Reached by a retirement within twelve months',
+                                }
+                skipped:
+                    type: array
+                    items:
+                        type: object
+                        required: [tenantId, subscriptionId, reason]
+                        properties:
+                            tenantId: { type: string }
+                            subscriptionId: { type: string }
+                            reason:
+                                {
+                                    type: string,
+                                    enum:
+                                        [
+                                            ended,
+                                            cancelled-before,
+                                            changes-before,
+                                            no-term,
+                                            already-told,
+                                        ],
+                                }
+                blockers:
+                    type: array
+                    description: 'Empty where it may be announced as it stands'
+                    items:
+                        type: object
+                        required: [code, message, params]
+                        properties:
+                            code: { type: string, description: 'RETIREMENT_*' }
+                            message: { type: string }
+                            params: { type: object }
+
+        RetirementAnnouncement:
+            type: object
+            required: [replacementPlanVersionId, subscriptionIds]
+            properties:
+                replacementPlanVersionId: { type: string, format: uuid }
+                subscriptionIds:
+                    type: array
+                    description: 'The subscriptions the operator was shown in the preview'
+                    items: { type: string }
+
+        VersionRetirement:
+            type: object
+            required: [id, retired, replacement, announcedAt, announcedBy]
+            properties:
+                id: { type: string }
+                retired: { $ref: '#/components/schemas/RetiredVersionRef' }
+                replacement: { $ref: '#/components/schemas/RetiredVersionRef' }
+                announcedAt: { type: string }
+                announcedBy: { type: string }
+
+        RetirementAnnounced:
+            type: object
+            required: [retirement, told, failed]
+            properties:
+                retirement: { $ref: '#/components/schemas/VersionRetirement' }
+                told: { type: integer, description: 'Notices sent at once' }
+                failed: { type: integer, description: 'Notices the next run sends' }
+
+        RetiredBundleVersionRef:
+            type: object
+            required: [bundleVersionId, bundleKey, version]
+            properties:
+                bundleVersionId: { type: string }
+                bundleKey: { type: string }
+                version: { type: integer }
+
+        BundleVersionSide:
+            description: >-
+                An add-on version as the subscribers compare it, at its own prices; each booking
+                is told the prices beside its plan. A price of null is a rhythm it is not sold in
+            allOf:
+                - $ref: '#/components/schemas/RetiredBundleVersionRef'
+                - type: object
+                  required: [label, features, quotas, monthlyNet, yearlyNet]
+                  properties:
+                      label: { type: string }
+                      features: { type: array, items: { type: string } }
+                      quotas: { type: object, additionalProperties: { type: number } }
+                      monthlyNet: { type: [number, 'null'] }
+                      yearlyNet: { type: [number, 'null'] }
+
+        BundleRetirementPreview:
+            type: object
+            required: [retired, replacement, changes, asOf, reached, skipped, blockers]
+            properties:
+                retired: { $ref: '#/components/schemas/BundleVersionSide' }
+                replacement: { $ref: '#/components/schemas/BundleVersionSide' }
+                changes:
+                    type: array
+                    description: 'Every difference at the two versions own prices'
+                    items: { type: object }
+                asOf: { type: string, description: 'ISO-8601: the moment it is computed for' }
+                reached:
+                    type: array
+                    items:
+                        type: object
+                        required:
+                            [
+                                tenantId,
+                                subscriptionId,
+                                subscriptionBundleId,
+                                planKey,
+                                planCycle,
+                                billingCycle,
+                                effectiveAt,
+                                lastDayToCancel,
+                                reachedRecently,
+                            ]
+                        properties:
+                            tenantId: { type: string }
+                            subscriptionId: { type: string }
+                            subscriptionBundleId: { type: string }
+                            planKey: { type: string, description: 'The plan beside it at the date' }
+                            planCycle: { type: string }
+                            billingCycle: { type: string, description: 'The booking rhythm' }
+                            effectiveAt:
+                                { type: string, description: 'ISO-8601: an end of its period' }
+                            lastDayToCancel:
+                                { type: string, description: 'ISO date, UTC: the day before' }
+                            reachedRecently:
+                                {
+                                    type: boolean,
+                                    description: 'Its subscription was reached by a retirement within twelve months',
+                                }
+                skipped:
+                    type: array
+                    items:
+                        type: object
+                        required: [tenantId, subscriptionId, subscriptionBundleId, reason]
+                        properties:
+                            tenantId: { type: string }
+                            subscriptionId: { type: string }
+                            subscriptionBundleId: { type: string }
+                            reason:
+                                {
+                                    type: string,
+                                    enum:
+                                        [
+                                            ended,
+                                            cancelled-before,
+                                            changes-before,
+                                            no-term,
+                                            already-told,
+                                        ],
+                                }
+                blockers:
+                    type: array
+                    description: 'Empty where it may be announced as it stands'
+                    items:
+                        type: object
+                        required: [code, message, params]
+                        properties:
+                            code: { type: string, description: 'BUNDLE_RETIREMENT_*, RETIREMENT_*' }
+                            message: { type: string }
+                            params: { type: object }
+
+        BundleRetirementAnnouncement:
+            type: object
+            required: [replacementBundleVersionId, subscriptionBundleIds]
+            properties:
+                replacementBundleVersionId: { type: string, format: uuid }
+                subscriptionBundleIds:
+                    type: array
+                    description: 'The bookings the operator was shown in the preview'
+                    items: { type: string }
+
+        BundleVersionRetirementRecord:
+            type: object
+            required: [id, retired, replacement, announcedAt, announcedBy]
+            properties:
+                id: { type: string }
+                retired: { $ref: '#/components/schemas/RetiredBundleVersionRef' }
+                replacement: { $ref: '#/components/schemas/RetiredBundleVersionRef' }
+                announcedAt: { type: string }
+                announcedBy: { type: string }
+
+        BundleVersionRetirement:
+            description: 'An add-on announcement as the list answers it, with how far it has come'
+            allOf:
+                - $ref: '#/components/schemas/BundleVersionRetirementRecord'
+                - type: object
+                  required: [progress]
+                  properties:
+                      progress:
+                          type: object
+                          description: 'Counted over the bookings it reached'
+                          required: [moved, waiting, overdue, ended, notTold, reminded]
+                          properties:
+                              moved: { type: integer }
+                              waiting: { type: integer }
+                              overdue: { type: integer }
+                              ended: { type: integer }
+                              notTold: { type: integer }
+                              reminded: { type: integer }
+
+        BundleRetirementAnnounced:
+            type: object
+            required: [retirement, told, failed]
+            properties:
+                retirement: { $ref: '#/components/schemas/BundleVersionRetirementRecord' }
+                told: { type: integer, description: 'Notices sent at once' }
+                failed: { type: integer, description: 'Notices the next run sends' }
+
         CatalogMarketingProjectionUpdate:
             type: object
             description: 'Partial update of a marketing projection'
@@ -2169,6 +2773,24 @@ components:
                 sendWelcomeMail: { type: boolean, default: true }
 
         # ────────── Subscription ──────────
+        CustomLimits:
+            type: object
+            description: >-
+                A tenant's own limits beside its plan — a negotiated contract, a pilot
+                (`CustomLimits` in @saasicat/core). A quota replaces the plan's value for that
+                quota; a feature is added to the plan's. Stored as JSON in
+                `subscriptions.customLimits`; a stored value in any other shape is not applied.
+            additionalProperties: false
+            properties:
+                quotas:
+                    type: object
+                    additionalProperties:
+                        type: integer
+                        minimum: -1
+                        description: 'quotaKey → maxValue (-1 = unlimited)'
+                features:
+                    type: array
+                    items: { type: string }
         SubscriptionDetail:
             type: object
             properties:
@@ -2181,9 +2803,7 @@ components:
                 canceledAt: { type: string, format: date-time }
                 isPilot: { type: boolean }
                 pilotEndsAt: { type: string, format: date-time }
-                customLimits:
-                    type: object
-                    additionalProperties: { type: integer }
+                customLimits: { $ref: '#/components/schemas/CustomLimits' }
                 customMonthlyNet: { type: number, format: decimal, nullable: true }
                 effectiveLimits:
                     type: object
@@ -2227,6 +2847,139 @@ components:
                                     contract was concluded; null where that line
                                     cannot be read.
 
+        SubscriberReadiness:
+            type: object
+            description: >-
+                Whether a subscriber can be given its next contract where a tax
+                adapter decides: the empty fields of the address an invoice
+                names, and the adapter's sentence where it supports no
+                treatment for the subscriber as it stands.
+            required: [ready, missing, taxRefusal]
+            properties:
+                ready: { type: boolean }
+                missing:
+                    type: array
+                    items:
+                        type: string
+                        enum: [addressLine1, postalCode, city, country]
+                taxRefusal:
+                    type: string
+                    nullable: true
+
+        AdminTenantSubscriber:
+            type: object
+            required: [subscriber, readiness]
+            properties:
+                subscriber:
+                    type: object
+                    nullable: true
+                    description: Null for a tenant that has no subscriber.
+                    required:
+                        [
+                            id,
+                            customerNumber,
+                            legalName,
+                            addressLine1,
+                            addressLine2,
+                            postalCode,
+                            city,
+                            country,
+                            business,
+                            vatId,
+                            vatIdValidated,
+                            taxNumber,
+                            migrated,
+                        ]
+                    properties:
+                        id: { type: string }
+                        customerNumber: { type: string }
+                        legalName: { type: string }
+                        addressLine1: { type: string, nullable: true }
+                        addressLine2: { type: string, nullable: true }
+                        postalCode: { type: string, nullable: true }
+                        city: { type: string, nullable: true }
+                        country: { type: string, nullable: true }
+                        business: { type: boolean, nullable: true }
+                        vatId: { type: string, nullable: true }
+                        vatIdValidated:
+                            type: boolean
+                            description: Whether the check that counts for the VAT id found it valid.
+                        taxNumber: { type: string, nullable: true }
+                        migrated:
+                            type: boolean
+                            description: Created from the application's own tenant record.
+                readiness:
+                    nullable: true
+                    description: Null where no tax adapter decides, or the tenant has no subscriber.
+                    allOf:
+                        - $ref: '#/components/schemas/SubscriberReadiness'
+
+        AdminVatIdCheckOutcome:
+            description: >-
+                A check of a VAT number as the operator is shown it — what the
+                service found, or why the check did not complete.
+            oneOf:
+                - type: object
+                  required: [completed, valid, checkedAt, service, counts]
+                  properties:
+                      completed: { type: boolean, enum: [true] }
+                      valid: { type: boolean }
+                      checkedAt: { type: string, format: date-time }
+                      service: { type: string }
+                      counts:
+                          type: boolean
+                          description: Whether it is the check that counts for the number held now.
+                - type: object
+                  required: [completed, reason]
+                  properties:
+                      completed: { type: boolean, enum: [false] }
+                      reason: { type: string }
+
+        AdminSubscriberCorrected:
+            type: object
+            required: [subscriber, vatIdCheck]
+            properties:
+                subscriber: { $ref: '#/components/schemas/AdminTenantSubscriber' }
+                vatIdCheck:
+                    nullable: true
+                    description: The check a VAT number got, where one was made.
+                    allOf:
+                        - $ref: '#/components/schemas/AdminVatIdCheckOutcome'
+
+        AdminSubscriberHistoryEntry:
+            description: One correction, change of the tax origin, or check of the VAT number.
+            oneOf:
+                - type: object
+                  required: [kind, at, by, previous, corrected, reason]
+                  properties:
+                      kind: { type: string, enum: [identity-corrected] }
+                      at: { type: string, format: date-time }
+                      by: { type: string }
+                      previous: { type: object, additionalProperties: true }
+                      corrected: { type: object, additionalProperties: true }
+                      reason: { type: string }
+                - type: object
+                  required: [kind, at, by, previous, changed, reason]
+                  properties:
+                      kind: { type: string, enum: [tax-origin-changed] }
+                      at: { type: string, format: date-time }
+                      by: { type: string }
+                      previous: { type: object, additionalProperties: true }
+                      changed: { type: object, additionalProperties: true }
+                      reason:
+                          type: string
+                          nullable: true
+                          description: Null for a change of the country with the contact details.
+                - type: object
+                  required: [kind, at, vatId, valid, service, counts]
+                  properties:
+                      kind: { type: string, enum: [vat-id-checked] }
+                      at: { type: string, format: date-time }
+                      vatId: { type: string }
+                      valid: { type: boolean }
+                      service: { type: string }
+                      counts: { type: boolean }
+
         # ────────── User ──────────
         AdminUserRow:
             type: object