Skip to main content
Connecting Meta sends your Fluid products to a product catalog in your Meta business, where Facebook, Instagram, and WhatsApp shopping and catalog ads use them. Fluid sends the product data and reads back Meta’s review of each product. Setup takes a person in a browser for one step: approving Fluid’s access in Meta.

Before you start

  • A Meta business portfolio (Business Manager) that owns at least one product catalog, created in Commerce Manager. Fluid sends products to an existing catalog; it doesn’t create one.
  • A person who is an admin of that business portfolio.
  • A Fluid API token for the company, or your own sign-in with fluid login. It needs company admin access: Company settings permission to connect and disconnect, and Products permission to choose and fix products.
  • Install and sign in to the CLI:
Every fluid channels command prints JSON. Failures print a JSON error on stderr and exit with a non-zero code.

Steps

In a terminal, fluid channels walk meta takes you through these steps one question at a time: it opens the sign-in link, checks the connection, lets you search for the products to send, and asks before each change.
1

Start the connection

This prints the Meta sign-in url and, with --open, opens it in your browser. Nothing changes in Fluid until someone approves it in the next step. Without --open, send the url to the person who will approve it. The link works once and expires after 10 minutes; run connect again for a new one.
2

Approve Fluid in Meta

Sign in to Facebook as an admin of the business portfolio and approve the access Fluid asks for. Fluid connects the first business you manage and every catalog it owns, and lists products in the first. If Meta says the app isn’t available to you, contact Fluid support.Meta then sends the browser back to Fluid admin. The address ends in connect=ok when the connection saved, or connect=error&reason=... when it didn’t. Whatever the page shows, check the result from the CLI:
The step is done when connection.status is connected. connection.account names the catalog Fluid connected.
3

Choose the products

This changes live configuration: it sends products to Meta. Decide first between the whole catalog and selected products; see Whole catalog or selected products.
To send only some products, name them instead:
The output’s added counts the products sent. Each one starts as a draft and publishes in the background.
4

Check the sync

listings.byStatus counts the listings in each state and listings.issues counts the ones that need you. Publishing and Meta’s review take from minutes to a few days. Check again later, backing off between checks, rather than in a loop.
5

Fix rejected products

Each issue has an action and a hint that says what to fix. Fix the product in Fluid, then:
  • For action: retry, retry every failed publish at once. This changes live configuration: fluid channels issues meta --retry --yes.
  • For action: fix_and_relist, remove the product and add it again so the corrected version is sent: fluid channels catalog meta --remove 4127 --yes, then --add 4127 --yes.
  • For action: resolve_on_channel, Meta took the listing down. Check the reason in Meta.
The step is done when count is 0.

Whole catalog or selected products

Fluid lists the products you send, one listing per product. There’s no setting that keeps the whole catalog in step with Meta on its own, so the choice is about which products you send now and how you add new ones later. Start with a few products if you haven’t sold on Meta before. You’ll see what Meta rejects before you send everything. Each product needs, before it’s sent:
  • A SKU on every active variant, unique across the products you list on Meta.
  • At least one active variant.
  • A title, description, price, and image. A product with no image of its own is sent with your company’s fallback image, which Meta’s review may reject.
A product missing one of these fails to publish and shows up in fluid channels issues meta. Meta reviews each product for every surface it’s tagged for, such as Facebook shops, Instagram, and WhatsApp. review shows each surface’s result. auditStatus rolls them up: audit_failed if any surface rejected it, auditing while any is pending, and approved once all approve. Edits you make in Fluid after a product is sent, including price changes, aren’t sent to Meta. Remove the product and add it again to send the current version. Fluid sends each variant’s stock status as it stands when the product is sent. A variant counts as in stock when it doesn’t track inventory, is set to Continue selling when out of stock, or has stock available: in the channel’s mapped warehouse if one is set, otherwise across all your warehouses. Later stock changes aren’t sent either. To take products off Meta, use --remove with product IDs, or --remove-all for every listed product. Removing a product deletes it from the Meta catalog.

What the status means

Troubleshooting

  • connect fails with 422. Fluid couldn’t start the connection, usually because the channel isn’t set up for your company yet. Contact Fluid support.
  • The address after approving ends in connect=error. The reason says why. invalid_state means the link was used twice or expired: run connect again for a new one.
  • The reason is no_business. The Facebook account you approved with doesn’t manage a business portfolio. Sign in as an admin of one and run connect again.
  • The reason is no_catalogs. The business portfolio owns no product catalog. Create one in Commerce Manager, then run connect again.
  • A command fails with 404. The company has no Meta connection. Run step 1.
  • A command fails with 403. Your token lacks the permission that command needs: Company settings for the connection, Products for products.
  • Adding or removing products fails with 422. The connection isn’t active. Check connection.status and reconnect if it isn’t connected.

Disconnect

Both commands change live configuration. Disconnecting doesn’t take your products off Meta: they stay listed and stop syncing, and you can’t remove them through Fluid until you reconnect. Remove them first, as above, unless you want them to stay. Fluid forgets its token and stops syncing. The output’s stillListed counts the products left on Meta.

Use the API directly

The CLI calls these company operations, all authenticated with a Bearer token:
  1. Start the Meta business-login connect flow, which returns the sign-in url.
  2. Get the company’s Meta commerce connection.
  3. Publish Fluid products to the connected Meta catalog.
  4. List the company’s Meta catalog listings.
  5. Retry a failed Meta catalog listing publish.
  6. Unpublish a Meta catalog listing.
  7. Disconnect the company’s Meta commerce connection.
For the whole catalog, the CLI reads your active products from Fluid’s product list and sends their IDs to the publish operation in batches of 50. Retrying only works on a listing whose publish failed.

Choose the ad account for ads

To prepare Facebook and Instagram ads, Fluid needs to know which ad account, Facebook Page and Instagram account the company advertises from. Connecting Meta asks for ads access in the same login. Until Meta’s app review approves that access, Meta grants it only to people with a role on Fluid’s Meta app. In the admin, open Settings › Sales Channels › Meta Commerce and use the Ad account card. Or use the API:
  1. List the Meta ad accounts and Pages the connection can reach. It reads them live from Meta and returns ad_accounts and pages; each Page carries its linked instagram_account.
  2. Select the Meta ad account to advertise from with ad_account_id, page_id and, to also advertise on Instagram, instagram_account_id. Use ids from step 1: Fluid checks each one with Meta before it saves the choice.
  3. Get the selected Meta ad account or clear it.
Choosing the ad account needs Company settings permission. Your ad account pays Meta directly, and Fluid never handles ad spend. To launch paused campaigns into this account, see Connect ad accounts and launch ads.
  • 422 with missing_ads_permission. Meta didn’t grant ads access. Run connect again and allow ads access, or wait for Meta’s app review.
  • 422 with unknown_ad_account, unknown_page or unknown_instagram_account. Meta no longer lists that id for this connection. List the accounts again.
  • 409. The connection is disconnected or expired. Run connect again.