Meta 2-Tier Onboarding — Dev Runbook (Errors, Graph API, Ads Readiness)

Audience: Engineering starting the product worker. Captures everything we hit in the Jun 2026 dev spike — errors, fixes, access quirks, pixel fields from Graph API, and what still blocks live ads.

Related: Implementation pack · ADR 0003 · meta-dev/ · specs/provisioning/

1. Ads readiness (dev smoke)

Infrastructure verified in Jun 2026 dev spike. Run audit-readiness.ps1 for a snapshot, run-2tier-phase5-verify.ps1 for spend_cap + Page linkage, probe-smoke-campaign.ps1 -Create for PAUSED campaign+adset.

1b. Page linkage via client_pages

When the child BM is created with shared_page_id in owned_businesses, Meta attaches the Page to the child BM as a client page.

Onboarding worker (step 6): verify client_pages contains the OAuth Page with ADVERTISE task; store meta_page_id; campaigns use promoted_object.page_id.

1c. spend_cap — dev smoke vs production

API: POST /act_{id} with spend_cap={minor_units} (TRY → kuruş, 100 minor = 1.00 TRY).

Production: billing/plan module passes credit_sub_limit_try × 100 minor units. Dev script default: -SpendCapTryMinor 100 (attempts 1 TRY, accepts Meta floor).

./run-2tier-phase5-verify.ps1 -SpendCapTryMinor 100

2. Pixel — fetch from Graph API (do not hand-write in prod)

After POST /act_{id}/adspixels, always GET the pixel for install code and health probes.

2.1 Recommended GET fields

GET /{pixel-id}?fields=id,name,code,last_fired_time,creation_time,data_use_setting,is_created_by_business,is_unavailable,owner_business

Token: child BM system user · appsecret_proof required on all calls when app setting enabled.

Alternate (list on account):

GET /act_{id}/adspixels?fields=id,name,last_fired_time,is_created_by_business

2.2 Verified dev response (Jun 2026)

Product rule: buildImplementationPack() calls fetchPixelFromGraph() and stores code in the pack. Fallback to template only if GET fails (log + HITL).

Reference: specs/provisioning/examples/tourism-onboarding.worker.ts · Zod: implementationPack.ts

2.3 Ad account fields for readiness audit

GET /act_{id}?fields=name,account_status,currency,spend_cap,amount_spent,balance,disable_reason
GET /{child_bm}/client_pages?fields=id,name,permitted_tasks
GET /act_{id}/campaigns?fields=id,name,status&limit=5

Scripts: meta-dev/fetch-pixel-details.ps1, meta-dev/audit-readiness.ps1

3. Graph API payload reference (verified)

All POST requests need access_token + appsecret_proof (HMAC-SHA256 of token with app secret).

Step 1 — Child BM

POST /{parent_bm_id}/owned_businesses

Step 2 — Child system user token

POST /{child_bm_id}/access_token

2b. Child system user scopes

Always request the full set at POST /{child_bm}/access_token:

ads_management,ads_read,business_management,catalog_management

Catalog API use case on the app ≠ catalog_management on system user token. With Catalog API enabled in App Dashboard → Use cases, minting still returns OAuth 100 / subcode 1690239 until App Review approves catalog_management.

Scripts: meta-dev/lib/child-system-user-scopes.ps1, run-2tier-phase1.ps1, refresh-child-token-catalog.ps1, probe-child-token-scopes.ps1.

2c. Catalog App Review gate (Kobico verified BM + test catalog)

Production rule: catalog is owned by the child BM — never created on parent and shared down.

Meta App Review for the Catalog API use case typically requires:

1. Business verification (PRE-8) on Kobico parent BM
2. Test catalog — create and manage a sample catalog via the app on the verified BM (App Review wizard)
3. catalog_management approved on system user tokens

Until all three are done, child token mint returns OAuth 1690239 for catalog_management and phase 3–4 scripts exit with instructions.

After approval: re-run refresh-child-token-catalog.ps1 → run-2tier-phase3-catalog.ps1 → run-2tier-phase4-feed.ps1 on a child BM under Kobico verified parent BM.

Step 3 — Ad account

POST /{child_bm_id}/adaccount

Step 4 — Spend cap

POST /act_{id}
Body: spend_cap={minor_units}

Plan credit_sub_limit_try × 100 for TRY kuruş.

Step 5 — Pixel

POST /act_{id}/adspixels
Body: name=...

Then GET pixel (§2) for code.

Step 6 — Verify Page on child BM

GET /{child_bm}/client_pages?fields=id,name,permitted_tasks

Confirm OAuth Page ID is present with PROFILE_PLUS_ADVERTISE. Script: run-2tier-phase5-verify.ps1

Step 7 — System user on ad account

POST /act_{id}/assigned_users
Body: user={child_system_user_id}&tasks=MANAGE,ADVERTISE,ANALYZE&business={child_bm_id}

Step 8 — Catalog on child BM (ecommerce / tourism + feed)

Token: child system user with catalog_management (App Review + PRE-8).

POST /{child_bm}/owned_product_catalogs
POST /{catalog_id}/product_sets
POST /{catalog_id}/product_feeds
POST /{feed_id}/uploads
POST /act_{id}/catalogs

Verify: GET /{child_bm}/owned_product_catalogs contains the catalog.

Script: run-2tier-phase3-catalog.ps1, run-2tier-phase4-feed.ps1

4. Errors we hit — and fixes

5. Access & permission issues

6. Code artifacts (copy to product monorepo)

7. Tourism — example implementation direction

Vertical: tourism (e.g. Kalkan Villa–style property listings)

Flow:

1. Client completes portal → OAuth Page + feed URL (https://…/feed.php)
2. Worker runs steps §3 (1–8 if catalog SKU)
3. fetchPixelFromGraph(pixelId) → store code in pack
4. buildImplementationPack('tourism') → Lead, ViewContent, InitiateCheckout, Purchase snippets
5. Portal Screen 7 → client IT installs pixel + events
6. Health job polls last_fired_time → green → A2 launch allowed
7. Campaign execution (separate module) creates paused DPA / lead gen campaign

Primary optimize event: Lead (inquiry) or Purchase (online booking)

See full TypeScript: tourism-onboarding.worker.ts

Client install example (after pack generated):

// From implementation_pack.meta — base pixel already in <head> via pixel.code from Graph
fbq('track', 'Lead');  // inquiry form success

fbq('track', 'ViewContent', {
  content_type: 'product',
  content_ids: ['VILLA-123'],
});

fbq('track', 'Purchase', {
  value: 15000.00,
  currency: 'TRY',
  content_ids: ['VILLA-123'],
  content_type: 'product',
});

8. Related documents

• Onboarding implementation pack
• Onboarding provisioning spec §5b
• Meta Ads dev verification
• Onboarding API cross-check §4