Decisions
ADR 0003: Meta Tenant Model — 2-Tier Child BM (Accepted)
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 (Kobi 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, Kobi 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
Primary model (production) — 2-Tier from client #1
Use child BM per tenant for all clients once PRE-10 is active. Do not run a separate “single-BM pilot lane” in production when 2-Tier is available — one architecture everywhere.
| Phase | Model |
|---|---|
| Onboarding | Client portal OAuth → child BM → child system user → ad account + assets |
| 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) |
Fallback only — single parent BM (≤5 ad accounts)
Use only while PRE-10 / 2-Tier API access is pending:
POST /{parent_bm_id}/adaccounton Kobi parent BM (system user)- Same Connect Meta + IG OAuth for Page/IG assets
- Retire this path once 2-Tier is live; migrate existing tenants to child BMs when scaling
Development & testing
Test the 2-Tier flow in Development mode — no need to build or maintain a separate “1-tier test harness” for ≤5 clients.
| Environment | 2-Tier testing | Notes |
|---|---|---|
| Dev mode | ✅ Yes | Meta limits child BM creation in dev (typically ~2 child BMs until business_management app review). Sufficient to prove OAuth → owned_businesses → child system user → ad account. |
| Production | ✅ After PRE-10 | Full client count; confirm per-user / per-page limits with Meta rep |
We do not need a dedicated single-BM “pilot architecture” in code if the team commits to 2-Tier — only a temporary fallback branch when APIs are unavailable.
Onboarding sequence (2-Tier)
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_registrystoresparent_bm_id,child_bm_id,child_system_user_id, Page/IG asset IDs — not onlyact_*.- 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 with
provisioning_mode: '2tier' | 'single_bm_fallback'.
Related decisions
| ID | Topic | Status |
|---|---|---|
| S1 | Meta tenant model | ✅ Locked — this ADR |
| B1 | Meta 5-account API cap | Mitigated by 2-Tier; fallback until PRE-10 |
| PRE-10 | 2-Tier API access | Required for production 2-Tier |