Meta Product Catalog

Sync product data from your warehouse to Meta Commerce Manager catalogs. Keep your product catalog up to date for Advantage+ Shopping campaigns, dynamic ads, and Facebook/Instagram Shops with automated product data syncs.

Prerequisites

• A Meta Business Manager account
• A product catalog created in Meta Commerce Manager
• Your Catalog ID (found in Commerce Manager > Catalog > Settings)
• A system user token or OAuth connection with catalog_management permission

Permissions

Your Meta app or system user must have the following permissions:

The system user must be assigned to the catalog with Full Control access in Business Manager > Data Sources > Catalogs.

Authentication

SignalSmith supports two authentication methods. System user tokens are recommended for production.

System User Token (Recommended)

1. Go to Meta Business Manager > Business Settings
2. Navigate to Users > System Users and select or create a system user with Admin access
3. Click Add Assets, select Catalogs, choose your target catalog, and grant Full Control
4. If you have a Meta app, click Add Assets > Apps and assign it to the system user
5. Click Generate New Token, select your app, and check the catalog_management permission
6. Set token expiration to Never for production use
7. Click Generate Token and copy the token immediately
8. In SignalSmith, select the System User Token tab and paste the token

OAuth 2.0

1. Click Connect with OAuth in SignalSmith
2. Sign in with your Facebook Business account
3. Authorize the requested permissions (catalog_management, ads_management)

OAuth tokens expire after 60 days of inactivity. SignalSmith refreshes them automatically.

Configuration

Supported Operations

Sync Modes

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

These fields are required for every product item synced to the catalog.

Default Destination Fields

Required Fields

id, title, description, availability, condition, price, link, image_link, brand

Common Optional Fields

sale_price, product_type, gtin, mpn, color, size, gender, age_group, material, item_group_id, additional_image_link

Custom Labels

custom_label_0 through custom_label_4 — use these to create custom product sets for campaign targeting. For example, use custom_label_0 for margin tier and custom_label_1 for seasonal category.

How It Works

SignalSmith reads product rows from your model query, applies field mapping, and batches products into groups of up to 3,000 items per API call to Meta’s Catalog Batch API (POST /{catalog_id}/items_batch).

Each product is sent as an upsert operation — new products are created and existing products (matched by id) are updated. The API supports up to 5,000 items per request, but SignalSmith uses 3,000 for optimal reliability.

The response includes per-item validation status. Products with errors (invalid URLs, missing required fields, format issues) are reported individually while valid products proceed successfully.

Product ID Matching

The id field is the primary identifier for matching products between your warehouse and Meta’s catalog. This must be consistent:

• Use the same ID format as your Meta Pixel’s content_id parameter for dynamic ads to work
• IDs are case-sensitive
• Once a product is created with an ID, the ID cannot be changed — only the product data can be updated

Item Group ID

Use item_group_id to group product variants (e.g., different sizes or colors of the same product). All variants with the same item_group_id are displayed as a single product with variant options in Facebook/Instagram Shops.

Best Practices

Product ID consistency

Use the same product IDs in your catalog as in your Meta Pixel content_id events. This enables dynamic ads to match viewed/carted products to catalog items for retargeting.

Image quality

Product images must be at least 500x500 pixels. Higher resolution images (1024x1024 or larger) display better in ads and Shops. Use clean product photography on white backgrounds for best results.

Custom labels for targeting

Use custom_label_0 through custom_label_4 to segment products by business attributes (margin, season, clearance, bestseller, etc.). These labels can be used to create product sets for targeted Advantage+ campaigns.

Price formatting

Always include the ISO 4217 currency code with the price (e.g., 29.99 USD, 19.99 EUR). Prices without currency codes may be rejected or misinterpreted.

Scheduling

For e-commerce catalogs with frequent price and availability changes, schedule syncs hourly or every few hours. For more stable catalogs, daily syncs are sufficient.

Rate Limits

• Up to 3,000 product items per API call (API maximum is 5,000)
• Meta enforces catalog-level batch rate limits — error code 80014 indicates the limit has been reached
• SignalSmith automatically splits large syncs into multiple API calls
• If you encounter rate limiting, reduce sync frequency or contact Meta for higher limits

Troubleshooting

Catalog not found

Verify the Catalog ID in Commerce Manager > Catalog > Settings. The ID is the numeric value shown in the URL or settings page. Ensure your token has access to this specific catalog.

Authentication failed

Regenerate your system user token and verify it has catalog_management permission. For OAuth, re-authenticate to get a fresh token.

Product rejected: missing required fields

Every product must include id, title, availability, price, link, and image_link. Check your field mapping to ensure all required fields are mapped. Empty or null values in required fields cause the product to be rejected.

Invalid image URL

Product image URLs must be publicly accessible, return a valid image (JPEG or PNG), and be at least 500x500 pixels. URLs behind authentication, CDN restrictions, or returning 404 errors are rejected.

Invalid price format

Prices must include both the amount and ISO 4217 currency code separated by a space (e.g., 29.99 USD). Common mistakes: missing currency code, using comma as decimal separator, or including currency symbols ($29.99 instead of 29.99 USD).

Products not appearing in dynamic ads

Ensure the id field in your catalog matches the content_id parameter in your Meta Pixel events. IDs are case-sensitive. Also verify the catalog is linked to your Ad Account in Commerce Manager > Catalog > Settings > Connected Assets.

Rate limit exceeded (error 80014)

Meta enforces per-catalog batch rate limits. Reduce sync frequency, lower batch sizes, or stagger syncs across multiple catalogs. For very large catalogs (100K+ products), consider scheduling during off-peak hours.

Custom labels not filtering correctly

Custom label values are case-sensitive. Ensure your warehouse data uses consistent casing. Labels must be plain text — special characters or very long values may cause issues in product set filters.