Onboarding Provisioning Spec

Purpose

Operational spec for what gets created during onboarding, how plan/SKU drives limits, and which sub-items run per platform — including pixels, catalogs, events by business type, and client-consent social linking.

API method names: onboarding-api-cross-check.md. Process flow: onboarding.md.

1. Plan / SKU entitlements (drive all limits)

Each client contract maps to a plan_id (SKU). The onboarding orchestrator reads plan_entitlements before creating any platform object. Limits are stored on tenant_registry and enforced by guardrails + Cost Guard — not honor-system.

Illustrative plan matrix (tune before launch)

# Illustrative — tenant_registry.provisioning
tenant_id: uuid
plan_id: standard_v1
vertical: health
entitlements:
  monthly_media_cap_try: 150000
  credit_sub_limit_try: 175000
  channels: [google_ads, meta, ga4, crm]
  catalogs: []
  meta_spend_cap_try: 175000
  optimization_cycles_per_month: 24

Upgrade path: plan change → orchestrator updates caps (Meta spend_cap, internal guardrails, entitlement row) — does not recreate ad accounts unless channel added.

2. Agency credit line & account limits

Agency master (Kobi ops — once per platform)

Clients never enter payment details. Kobi finance configures agency billing before any tenant onboarding. New ad accounts inherit the master profile. Clients receive Kobi monthly invoices only (ERP).

Per-tenant (automated from plan_id + billing source)

Budget lifecycle (programmatic — not billing warnings)

ONB-11: tenant provisioned without credit_sub_limit or monthly_media_cap → block client.onboarding.completed (per-tenant config bug — not agency billing).

Never ONB for: MCC monthly invoicing, Meta credit, TikTok BC funding, Kobi-entity business verification — those are PRE-* one-time (cross-check).

Agency business verification (Kobi entity)

Shell accounts inherit verified agency masters. Domain verification (client website DNS) is a separate, optional per-tenant step — not business entity docs.

3. End-to-end provisioning flow

4. Vertical templates — pixels, events, catalogs

Onboarding Agent applies provisioning_template.{vertical} — not one-size-fits-all.

Event sets by business type

Sub-items created per template (checklist)

¹ Special Ad Categories are only HOUSING, EMPLOYMENT, FINANCIAL_PRODUCTS_SERVICES (replaced CREDIT Jan 2025), ISSUES_ELECTIONS_POLITICS. No vertical defaults to a category — the flag is set per-ad only when the creative/offer actually concerns one of those topics. Health and schools default to NONE. See meta-ads — Compliance notes.

Templates versioned in playbook.provisioning.{vertical}; changes require ops publish + audit.

5. Meta + Instagram linking (client consent, minimal friction)

Goal: Client links owned Facebook Page + Instagram Professional account to Kobi BM without manual Business Manager email ping-pong where possible.

Client portal flow (“Connect Meta & Instagram”)

1. Client already accepted ToS + data-sharing + Meta asset access (records consent_id, scopes, timestamp).
2. Client clicks Connect → Facebook Login for Business (or Meta Business Login) with Kobi app.
3. Requested permissions (minimize): pages_show_list, pages_read_engagement, pages_manage_metadata, business_management, instagram_basic, instagram_manage_insights (exact set TBD at app review).
4. Client selects Page + linked Instagram account in OAuth UI (Meta-hosted — user consent).
5. Backend receives short-lived token → exchanges → calls Marketing API:

Fallback (⚠️): POST /{kobi-bm-id}/client_pages partner invitation — client accepts in Meta UI if OAuth asset share fails.

Not required: client admin on Kobi BM; client never receives ad account ownership.

Instagram-only or Page-less clients

5b. Meta 2-Tier child BM provisioning

Decision: ADR 0003 — child BM per client is the primary production model (from client #1 once PRE-10 is active). Single parent BM (≤5 ad accounts) is fallback only while 2-Tier API access is pending.

Sources: 2-Tier overview · Setup child BM · Onboard at scale · owned_businesses

Why client OAuth is required for child BM

Creating a child BM uses the client’s user access token from Facebook Login — not the parent BM system user token.

Provisioning sequence (automated after OAuth)

¹ Requires PRE-10 (2-Tier API access via Meta rep). ² Requires PRE-2 extended credit on parent BM.

Development vs production

Fallback (PRE-10 pending)

Store on tenant_registry: parent_bm_id, child_bm_id, child_system_user_id, meta_provisioning_mode, shared_page_id.

6. Platform provisioning packages

6.1 Google Ads package

6.2 Meta package

6.3 TikTok package (if SKU)

6.4 GA4 package — ⏸ deferred (onboarding v1)

Not provisioned during onboarding v1. When enabled: property access, streams, key events, Ads link — see ga4-source-of-truth.md.

6.4b Implementation guide (Phase 1 — always)

6.5 Merchant Center package (ecommerce)

6.6 CRM package

6.7 Cross-cutting sub-items

7. Client consent surfaces (one portal, multiple gates)

All consents → consent_record with version, actor, timestamp; linked to onboarding_record.

8. Outputs (expanded onboarding_record)

{
  "tenant_id": "uuid",
  "plan_id": "standard_v1",
  "vertical": "health",
  "entitlements": { "monthly_media_cap_try": 150000, "credit_sub_limit_try": 175000 },
  "platform_ids": {
    "google_ads_customer_id": "1234567890",
    "meta_ad_account_id": "act_...",
    "meta_pixel_id": "...",
    "meta_page_id": "...",
    "meta_ig_id": "...",
    "ga4_property_id": "...",
    "merchant_center_id": null
  },
  "templates_applied": {
    "provisioning": "health_v3",
    "events": "health_v3"
  },
  "consents": ["tos_v2", "data_share_v1", "meta_assets_v1"],
  "tracking_checklist": { "ga4": "green", "meta_pixel": "green", "capi": "green" }
}

9. Agent vs client vs ops

10. Related documents

• Onboarding client portal — client-facing screens and completion summary
• Onboarding — SLA, process diagram
• Onboarding API cross-check — endpoint-level matrix
• Platform access & API readiness
• Meta Ads
• Data & tracking — UTM + event taxonomy
• Human-in-the-loop — A4 access approvals