meta_ads_products_add
Add a single product to a Meta Product Catalog. Uses retailer_id as an upsert key to update existing records instead of creating duplicates.
Instructions
Adds a single product to a Meta Product Catalog. Returns the new product_id. Mutating, reversible via rollback_apply. For bulk ingestion prefer a scheduled feed (meta_ads_feeds_create) — Meta rate-limits single-product adds aggressively. Meta requires a stable retailer_id per product; adding a second product with the same retailer_id updates the existing record rather than creating a duplicate.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | Yes | Meta Ads account ID in the format 'act_XXXXXXXXXX' (e.g. 'act_1234567890'). Optional — falls back to META_ADS_ACCOUNT_ID from the configured credentials. The leading 'act_' prefix is required. | |
| catalog_id | Yes | Catalog to add the product into. | |
| retailer_id | Yes | Advertiser's stable SKU / product identifier. Used as the upsert key — a second add with the same retailer_id updates the existing product. | |
| name | Yes | Product display name shown in DPA / Collection ads. | |
| description | No | Product description. Shown on some placements and surfaces; Meta also uses it as a weak targeting signal. | |
| availability | Yes | Inventory status. Meta suppresses 'out of stock' and 'discontinued' items from DPA delivery. | |
| condition | Yes | Product condition. Required by Meta for catalog eligibility in most verticals. | |
| price | Yes | Price as a string with currency code, e.g. '1000 JPY', '9.99 USD'. Meta parses the string into amount + ISO currency. Must match the catalog's supported currencies. | |
| url | Yes | Product landing page URL. Must be HTTPS and reachable — Meta periodically probes URLs and marks broken ones. | |
| image_url | Yes | Primary product image URL. HTTPS, publicly fetchable. Meta recommends at least 500×500px. | |
| brand | No | Brand name. Optional but improves match quality for broad-intent DPA shoppers. | |
| category | No | Category path using Google Product Taxonomy format (e.g. 'Apparel & Accessories > Clothing > Tops'). Optional but strongly recommended for multi-category catalogs. |