Dossier Kobico Digital Ads · Board pack · v1.9.31 Board pack · v1.9.31

Decisions

ADR 0003: Meta Tenant Model — 2-Tier Child BM (Accepted)

Created 11 Jun 2026·Updated 17 Jun 2026

Latest change: Rebrand dossier from Kobi to Kobico

Status

Accepted — 11 Jun 2026. Decision owned by the founder.

Locks S1 (gameplan §5).

Context

Meta caps API-created ad accounts at 5 per Business Manager on a single BM. Beyond that requires the official 2-Tier Business Manager solution — a parent BM (Kobico agency) that creates a child BM per client via POST /{parent_bm_id}/owned_businesses.

Child BM creation cannot be done with the parent BM system user token alone. Meta requires the client’s user access token (from Facebook Login / OAuth) plus a Facebook Page the client admins (shared_page_id). After the child BM exists, Kobico creates an Admin system user inside the child BM for day-to-day Marketing API automation (ad account, pixel, CAPI, campaigns).

PRE-10: Access to 2-Tier APIs is relationship-gated — request via a Meta representative (platform access).

Decision

One model only: child BM per tenant via 2-Tier for all clients — dev and production.

Phase Model
Onboarding Client portal OAuth → child BM (owned_businesses + shared_page_id) → child system user → ad account + assets
Page for ads GET /{child_bm}/client_pages — Page linked at child BM create; campaigns use promoted_object.page_id
Runtime Child BM system user token (Secret Manager, per tenant)
Billing Parent BM extended credit; share LOC + spend_cap to child BM (onboard at scale)

Meta caps API ad-account creation at 5 per parent BM — that is why every client gets a child BM, not multiple ad accounts on the parent.

Development & testing

Test the 2-Tier flow in Development mode only — scripts in meta-dev/.

Environment Notes
Dev mode ~2 child BMs typical until business_management app review — enough to prove full chain
Production PRE-10 (Meta rep) required before scale

Dev verification (Jun 2026)

Engineering verified the 2-Tier onboarding chain in app Development mode (Kobico Digital Ads (Dev)) using scripts in meta-dev/. Summary:

Step Verified Notes
owned_businesses → child BM ✅ User token + shared_page_id
Child system user + token ✅ Parent system user → POST /{child_bm}/access_token
Ad account in child BM ✅ Dev: card on child BM; no funding_id required in this run
Pixel + assigned_users ✅ Child system user token
Catalog + product set + feed ✅ (after Catalog App Review) POST /{child_bm}/owned_product_catalogs — child-owned; product set + feed on child token
Product feed / DPA ads ⬜ Not in scope of spike
Page on child BM GET /{child_bm}/client_pages ✅
Parent LOC share (PRE-2) ⬜ Production billing path — not dev card

Implications for build: onboarding worker always requests full scopes at child system user mint. Catalog is child-owned only (POST /{child_bm}/owned_product_catalogs). Ecommerce SKU catalog provisioning runs after Catalog API App Review + PRE-8 on Kobico parent BM — test catalog in review flow on verified BM, then re-run dev phases 3–4 on child BM.

Onboarding sequence (2-Tier)

Kobico backendMeta OAuth /Graph APIKobico portalClientKobico backendMeta OAuth /Graph APIKobico portalClientPick Facebook Page (+ IG)User token — not parentsystem userOngoing = child BM system usertokenToS + data sharingFacebook Login for BusinessUser access token + page_idPOST/{parent_bm_id}/owned_busine-ssesCreate Admin system user inchild BMPOST/{child_bm_id}/adaccountPixel, verify client_pages,catalog

Official sources (Meta)

Topic Link
2-Tier BM overview developers.facebook.com/docs/marketing-api/2tier-bm-solution/
Create child BM guide developers.facebook.com/docs/marketing-api/2tier-bm-solution/guides/setup-cbm/
Onboard clients at scale developers.facebook.com/docs/business-sdk/common-scenarios/onboard-at-scale/
owned_businesses edge Business owned businesses
System users System users
Ad account create Ad account (POST /{business-id}/adaccount)
Ad account limits (help) facebook.com/business/help/1026272311098874
Facebook Login for Business Facebook Login for Business

Consequences

  • tenant_registry stores parent_bm_id, child_bm_id, child_system_user_id, Page/IG asset IDs — not only act_*.
  • Onboarding portal Connect Meta & Instagram is required for 2-Tier (creates child BM + links assets) — see provisioning spec §5 and §5b.
  • PRE-10 on W0 critical path with Emre (Meta rep intro).
  • Implementation: one connector path — 2-Tier child BM only (implementation pack).
ID Topic Status
S1 Meta tenant model ✅ Locked — this ADR
B1 Meta 5-account API cap 2-Tier child BM per client — only architecture
PRE-10 2-Tier API access Required for production 2-Tier

References