Skip to main content
These company operations let a script or an AI agent run ads for a merchant: connect Meta and Google, choose the ad account, make images, launch a campaign, and report on it. Mist uses them when a merchant asks it to run ads; the Run ads with Mist help article describes that flow for merchants. Three rules hold for every launch:
  • Every campaign is created paused in the merchant’s own ad account, which bills it. The merchant switches it on in Meta Ads Manager or Google Ads. Fluid never switches a campaign on and never handles ad spend.
  • Fluid checks the copy before it sends anything. A line that makes a claim the platforms reject, such as a health claim or a guaranteed result, blocks the whole launch.
  • Fluid doesn’t mirror campaigns. It keeps a record of each launch and reads status and results live from Meta or Google when you ask.
All of these operations take a company Bearer token (Authorization: Bearer <token>) for a company admin. Connecting, choosing an account and launching need the Company settings permission; generating images needs Media. Droplet installation tokens are refused.

​
1. Connect Meta and Google

One login per platform covers both commerce and ads: A person has to approve the login in a browser. Open the url for them, wait for them to say they’re done, then read the connection once: Get the company’s Meta commerce connection or Get the company’s Google Merchant Center connection. A test store can’t connect.

​
2. Choose the ad account

Fluid launches only into the ad account the company chose. Read the choices live from the platform, then save one of them: On Meta, the choice is an ad account, the Facebook Page the ads run as and, optionally, the Instagram account linked to that Page. On Google, it’s one Google Ads account that is enabled and isn’t a manager account. Save only ids that the list returned. Fluid checks each id with the platform again before it saves, so an id typed in by hand or taken from another company fails. When an agent chooses for a merchant, show the merchant the list and let them pick.

​
3. Get images (Meta only)

Each Meta ad needs an https image_url. Use the product’s own images where one fits the placement. When none does, generate one:
  1. Generate ad images at an aspect ratio with a prompt, an aspect_ratio of 1:1, 4:5, 9:16 or 1.91:1, and, to base the images on a product, its product_id. It returns 202 with a generation id.
  2. Read an ad image generation until its status is completed or failed. Each completed image is saved to the company’s media library, and its url is ready to use as an image_url.
Generating images is charged to the company’s AI credits. An agent should ask the merchant before it generates. A generation result expires after an hour; the saved images don’t.

​
4. Launch

Send the approved copy to Launch a paused Meta campaign or Launch a paused Google Search campaign. Both return 201 with the launch record and the platform’s ids.
  • Meta creates a Traffic campaign, one ad set and one to five link ads, all paused.
  • Google creates a budget, a Search campaign, one ad group and one responsive search ad, with the campaign paused. Google applies it all at once, so a refused launch creates nothing.
The daily_budget is in the ad account’s minor currency units, such as cents for USD. Fluid adds UTM tags to the link_url, and the utm_campaign names the campaign in Fluid’s own reports. Retry safely with idempotency_key. Send a key that identifies the approved ads, such as a hash of them. If a request times out and you send it again with the same key, you get the first launch back instead of a second campaign. If that first launch hasn’t finished, you get 409 with launch_in_progress: check the ad account for the campaign before you launch again with a new key. Never tell a merchant an ad is live after a launch. It’s paused until they switch it on, and the platform may still review it.

​
5. Read results

List the company’s ads launches and List the company’s Google ads launches return the launch records, newest first. For one launch’s results, call Read a Meta launch’s campaign results or Read a Google launch’s campaign results. Fluid reads them live from the platform: the campaign’s current status, spend, impressions, clicks, click-through rate and cost per click, for the days from since to until. Without dates, the range runs from the launch date to today.

​
Errors

Failures put a machine-readable type in error.details.type. Branch on the type, not on the message. When the platform refuses a launch, the response is 502 and error.details.launch_id names the failed launch record. On Meta, any campaign parts created before the failure stay in the ad account, all paused.