Meta Catalog — operator setup guide

This guide walks an operator from "I have a Facebook account" to "the catalog-meta plugin is connected and pushing variants to a Meta Commerce Catalog." Follow it once per deployment; the credentials it produces go into admin settings under the meta group.

The integration is built on Meta's Catalog Batch API (POST /{catalog_id}/items_batch) plus the asynchronous Check Batch Request Status poller. Both endpoints require a Meta App configured with the right products and permissions, and an access token bound to a System User in the Business Manager that owns the catalog.

0. Prerequisites

You need all of these before you start. None of them are something we can create on your behalf.

1. A Facebook account that you control. The account becomes the OAuth initiator and the App developer.
2. A Meta Business Manager. If you don't have one, create one at https://business.facebook.com and verify your business email.
   • Free, but Business Verification is required before Meta will let your App use catalog_management against catalogs you don't directly own. For dev mode against your own catalog you can skip this.
3. A Product Catalog inside that Business. Create one at https://business.facebook.com/commerce_manager → Catalogs → Add catalog. Pick "Ecommerce" type. Note the numeric catalog id (visible in the URL once you open the catalog).
4. A public callback URL the Meta App can redirect a browser to. For local development this is almost always an ngrok or cloudflared tunnel; for staging it's the staging API URL. The URL must look like https://<host>/admin/meta/oauth/callback.

1. Create the Meta App

1. Go to https://developers.facebook.com/apps.
2. Click Create app.
3. Use case: Other (we don't fit Meta's narrow templates).
4. App type: Business. (Required so business_management + catalog_management are available.)
5. Display name: anything recognisable — e.g. <your-store-name> Catalog Sync.
6. App contact email: your email.
7. Business account: pick the Business Manager from step 0.2 above. If you skip this, you can attach the business later under Settings → Basic.
8. Click Create app, complete the captcha, and you land on the App Dashboard.

At this point the App is in Development mode. That's what we want — it lets you OAuth against catalogs owned by your own Business without going through App Review.

2. Capture App ID and App Secret

These are the two values our plugin needs in admin settings.

1. In the left rail of the App Dashboard, open Settings → Basic.
2. Copy the App ID (the numeric value at the very top). This goes into the meta.app_id setting.
3. Click Show next to App secret, complete the password challenge, and copy the value. This goes into meta.app_secret. Treat it like a password — anyone with it can mint tokens against your App.
4. Scroll to the bottom and click Save changes if you edited anything (e.g. added the privacy policy URL).

3. Add the Facebook Login product

1. From the left rail, click Add product (or Products if some already exist).
2. Find Facebook Login and click Set up.
3. When asked for a platform, pick Web (we don't ship a Meta-published webapp; the callback we serve counts as the web surface).
4. Site URL: paste the public API base URL (e.g. https://api.example.com or your ngrok URL). This is informational; the redirect URI list below is what's enforced.
5. Skip the SDK quickstart pages — we don't use the JS SDK. Click through to finish.

3a. Whitelist the OAuth callback

1. In the left rail under Facebook Login, open Settings.
2. Valid OAuth Redirect URIs: paste your full callback URL exactly — https://<host>/admin/meta/oauth/callback. You can list more than one if you need both staging and ngrok URLs.
3. Client OAuth Login: ON.
4. Web OAuth Login: ON.
5. Enforce HTTPS: ON (Meta requires HTTPS even in dev — ngrok / cloudflared satisfy this).
6. Embedded Browser OAuth Login: leave OFF unless you specifically need it.
7. Use Strict Mode for Redirect URIs: ON. Meta will reject any redirect that doesn't exactly match the list above.
8. Save changes.

4. Request the catalog + business permissions

The OAuth flow our plugin runs asks for two scopes:

• catalog_management — read/write product catalogs the user administers.
• business_management — list businesses, list catalogs under a business, create + assign System Users.

Both are Advanced Access permissions. In Development mode they work for App developers/admins/testers against their own assets, with no Meta App Review required.

1. In the left rail open App Review → Permissions and Features.
2. Find catalog_management. The status column will say "Standard Access" — that's fine for dev. (To go live against other people's catalogs you'd eventually click Request advanced access, which triggers App Review + Business Verification. Don't do that yet.)
3. Same for business_management.

You do not need to request public_profile, email, or any other scope — we deliberately keep the consent footprint to just these two.

5. Add yourself (and any other testers) as App roles

In Development mode, OAuth only works for users who have a role on the App.

1. Left rail → App Roles → Roles.
2. Click Add People.
3. Add your Facebook account as Administrator (or Developer or Tester; all three can OAuth in dev mode).
4. Repeat for any other tester accounts.
5. Each invitee gets a Facebook notification — they have to accept before they can OAuth.

The Facebook account that initiates the OAuth flow (step 7 below) must be on this list AND must have admin access to the Business Manager + Catalog from step 0.

6. (Optional) System User pre-creation

The plugin will create a System User named Supercommerce Catalog Sync inside your Business Manager automatically the first time you call POST /admin/meta/select-catalog. You don't have to pre-create one.

If you want to inspect / pre-create manually:

1. https://business.facebook.com → Business settings → Users → System users.
2. Click Add → System user, name it Supercommerce Catalog Sync, role Admin.
3. The plugin will detect the existing user by name and reuse it instead of creating a duplicate.

You do not need to mint a token here. The plugin mints a non-expiring System User access token bound to the App + catalog as part of select-catalog.

7. Wiring it into admin settings

Once you have App ID, App Secret, and the callback URL whitelisted, push them into the running API:

curl -sS -c cookies.txt -b cookies.txt -H "Content-Type: application/json" \
  -X POST "$API/auth/sign-in/email" \
  -d '{"email":"admin@admin.com","password":"<your-admin-password>"}'

curl -sS -b cookies.txt -H "Content-Type: application/json" \
  -X PATCH "$API/admin/settings/admin" \
  -d '{
    "meta": {
      "app_id":                  "1234567890",
      "app_secret":              "abcdef0123456789…",
      "redirect_uri":            "https://<your-public-host>/admin/meta/oauth/callback",
      "currency":                "INR",
      "storefront_base_url":     "https://shop.example.com",
      "storefront_product_path": "/product/{slug}",
      "default_condition":       "new",
      "sync_enabled":            true,
      "feed_mode":               "live"
    }
  }'

Verify the wiring lands cleanly:

curl -sS -b cookies.txt "$API/admin/meta/status" | jq .
# configuration.oauthClient should now be "configured".
# configuration.feed will still be "missing" until you pick a catalog.
# connected will still be false until OAuth completes.

8. Run the OAuth handshake

curl -sS -b cookies.txt "$API/admin/meta/oauth/start" | jq -r .authUrl

Open the returned URL in a browser while logged into the Facebook account from step 5. Approve the consent screen (you'll see two permissions listed — catalog_management and business_management). Facebook redirects to your callback URL; the plugin exchanges the code, swaps to a 60-day long-lived user token, and stores it.

You'll be redirected to <PUBLIC_ADMIN_URL>/settings/meta?connected=1 if PUBLIC_ADMIN_URL is set; otherwise the response body is { "connected": true }.

Confirm:

curl -sS -b cookies.txt "$API/admin/meta/status" | jq .
# connected=true, accountId="<your fb user id>", scope="catalog_management,business_management"

9. Pick a business + catalog

curl -sS -b cookies.txt "$API/admin/meta/businesses" | jq .

Pick one business + one catalog (from ownedCatalogs or clientCatalogs) and submit them:

curl -sS -b cookies.txt -H "Content-Type: application/json" \
  -X POST "$API/admin/meta/select-catalog" \
  -d '{
    "businessId":   "<paste>",
    "businessName": "<paste>",
    "catalogId":    "<paste>",
    "catalogName":  "<paste>"
  }' | jq .

What this does under the hood:

1. Creates (or reuses) a System User named Supercommerce Catalog Sync in the chosen business.
2. Assigns the chosen catalog to that System User with MANAGE access.
3. Mints a non-expiring System User access token bound to the App.
4. Overwrites the integration credential row with the new token (tokenKind flips from user to system_user).
5. Persists meta.business_id, meta.catalog_id, meta.system_user_id, meta.token_kind to admin settings.

After this the integration is fully connected. Status:

curl -sS -b cookies.txt "$API/admin/meta/status" | jq .
# configuration.feed="configured", selection.tokenKind="system_user", counts.synced=0

You're ready to bootstrap (POST /admin/meta/bootstrap) or just let the catalog/inventory event listeners drive the outbox naturally.

Troubleshooting

Going live

When you're ready to move out of Development mode:

1. Business Verification must be complete on the Business Manager (Settings → Security Center).
2. App Review for catalog_management and business_management. Each needs a recorded screencast of the OAuth + catalog selection flow and a written justification. Meta usually reviews in 3–10 business days.
3. Privacy Policy URL and Terms of Service URL must be set in App Settings → Basic.
4. Data Use Checkup: confirm how you handle each permission's data.
5. Switch the toggle in the App Dashboard from Development to Live.

After going live, OAuth works for any Business admin, not just users on the App Roles list.

Reference

• Catalog Batch API guide: https://developers.facebook.com/docs/marketing-api/catalog/guides/manage-catalog-items/catalog-batch-api/
• Catalog Batch API reference: https://developers.facebook.com/docs/marketing-api/catalog-batch/reference
• Check Batch Request Status: https://developers.facebook.com/docs/marketing-api/reference/product-catalog/check_batch_request_status/
• catalog_management permission: https://developers.facebook.com/docs/permissions/reference/catalog_management/
• Business Management — System Users: https://developers.facebook.com/docs/business-management-apis/system-users/install-apps-and-generate-tokens/
• Rate limits: https://developers.facebook.com/docs/marketing-api/overview/rate-limiting/
• Product data spec: https://www.facebook.com/business/help/120325381656392