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 (Kobico ops — once per platform)

Clients never enter payment details. Kobico finance configures agency billing before any tenant onboarding. New ad accounts inherit the master profile. Clients receive Kobico 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, Kobico-entity business verification — those are PRE-* one-time (cross-check).

Agency business verification (Kobico 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 Kobico 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 Kobico 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:

Not required: client admin on Kobico 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 for all tenants (2-Tier BM).

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)

Page linkage

See dev runbook §1b.

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

Development vs production

Store on tenant_registry: parent_bm_id, child_bm_id, child_system_user_id, shared_page_id, meta_catalog_id, meta_product_set_id (ecommerce SKU).

Dev verification (Jun 2026)

See ADR 0003 dev verification and meta-dev/README.md. Confirmed in Development mode:

1. Child BM → child system user → ad account → pixel (child system user throughout).
2. Billing (dev): card on child BM; ad account created without explicit funding_id. Production: parent LOC share (owning_credit_allocation_configs) — PRE-2.
3. Catalog (ecommerce): POST /{child_bm_id}/owned_product_catalogs (child token, catalog_management) + POST /{catalog_id}/product_sets + POST /{catalog_id}/product_feeds + POST /{feed_id}/uploads. Requires Catalog API App Review + PRE-8 on Kobico parent BM before automation. Registry: meta_catalog_feed_id, meta_catalog_feed_url.
4. Human BM UI: not required for automation; assign business_users ADMIN via API if finance UI needed for ops/debug.

6. Platform provisioning packages

6.1 Google Ads package

6.2 Meta package

v1 publish (implementation pack spec) · CAPI + offline = v2

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)

Source of truth: Onboarding implementation pack — orchestrator buildImplementationPack(vertical); not hand-written per client.

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": "...",
    "meta_catalog_id": null,
    "meta_catalog_feed_url": null,
    "ga4_property_id": "...",
    "merchant_center_id": null
  },
  "implementation_pack": {
    "schema_version": "1.0",
    "artifact_uri": "gs://.../implementation_pack.json",
    "generated_at": "2026-06-14T12:00:00Z"
  },
  "templates_applied": {
    "provisioning": "health_v3",
    "events": "health_v3"
  },
  "consents": ["tos_v2", "data_share_v1", "meta_assets_v1"],
  "tracking_checklist": { "ga4": "pending", "meta_pixel_browser": "pending", "capi": "v2_deferred" },
  "tracking_relay": {
    "enabled": false,
    "delivery_mode": "first_party",
    "cname_host": null,
    "loader_url": null,
    "cmp_mode": "kobi_cmp",
    "cmp_vendor": "kobi",
    "cmp_partnership_id": null,
    "consent_profile": "tr_kvkk",
    "platform": null,
    "enabled_modules": [],
    "privacy_policy_url": null,
    "banner_locales": ["tr", "en"],
    "google_consent_mode": true
  }
}

tracking_relay (Phase 2a+): Populated when client opts into Relay SKU. Defaults: cmp_mode = kobi_cmp, cmp_vendor = kobi, delivery_mode = first_party. Set cmp_mode = client_cmp + vendor when BYO CMP; kobi_bundled_cmp + cmp_partnership_id when leadership closes a global CMP partnership or interim portfolio bundle. See ADR 0005.

9. Agent vs client vs ops

10. Related documents

• Onboarding implementation pack — auto-generated client guide per vertical; v1/v2 split
• Onboarding client portal — client-facing screens and completion summary
• ADR 0005: k.js relay micro-modules & CMP
• 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