> ## Documentation Index > Fetch the complete documentation index at: https://docs.fluid.app/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract. > Authenticate with the header Authorization: Bearer ; public storefront read endpoints require no auth. > To sign a new merchant up for Fluid programmatically, call POST https://api.fluid.app/api/company with no credentials, as described in /api/agent-signup. Do not automate the signup form or book a demo. Before authenticated calls are possible, the merchant must sign the agent in to the Fluid CLI with the emailed code and --shop set to the company's fluid_shop (which also confirms the signup), or open the emailed confirmation link and give the agent an API token. > After signup, to launch a merchant's store (back-office sync, payments onboarding, store setup, a theme copied from their current site, and a preview link before billing), follow /api/agent-launch. > Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null. > When the same operation exists on more than one surface, use the newest: dated API versions are newer than unversioned ones, and later dates win (v2026-04 > v2025-06 > unversioned v0/v1.1). Fall back to a legacy or unversioned operation only when no newer versioned equivalent exists — the company-v0 notes below list the known superseded operations. The same applies to /api/company/v1 and /api/v1/... paths: prefer a newer documented equivalent, and use one only when none exists (/api/v1.1/... is distinct and documented in company-v0). Use page/per_page offset pagination only on an operation whose spec documents those params — mostly the unversioned company-v0 admin surface, plus some lists on other surfaces, versioned ones included; page every other list with cursors. > Fluid has three navigation APIs; don't mix them up. Storefront website menus (navigation bars, footers) are /api/menus and nested menu_items, in api-reference/content-v0.yaml (API Reference: Website > Navigation menus), with a how-to in themes/navigation-menus; their list uses flat page/per_page pagination. The Fluid mobile app's navigation is /api/v2/mobile_navigations, in api-reference/mobile-v2.yaml (API Reference: Mobile app > Navigation); its list also uses page/per_page. Portal navigations belong to a portal definition (Fluid OS), in api-reference/fluid-os-v0.yaml (API Reference: Portal > Portal navigation), and each has a platform of web or mobile. > The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas); api-reference/company-v0.yaml covers the legacy unversioned company admin surface (/api/... paths, bearer-authenticated except two operations that take no credential, POST /api/company (create a company) and GET /api/agreements/{id} — company settings and management, customers, users, roles, subscription plans, subscription bundles, subscriptions, media, pages, catch-ups, inventory levels, domains, agreements, and admin order actions). company-v0 caveats: it is the legacy v0 admin contract and its lists use flat page/per_page offset pagination, which is expected there despite the general cursor-pagination rule; where an operation exists in both company-v0 and a versioned spec, prefer the versioned spec — the subscriptions lifecycle (list/create/show/update, cancel, pause, reactivate, resume, retry, skip, failed-cycle-waiver, discounts) and subscription bundles are superseded by checkout-v2026-04, and company pages/media CRUD plus the public pages, categories, products, and media list endpoints are superseded by storefront-v2026-04. Subscription plan management (/api/subscription_plans, resource-wrapped {"subscription_plan": {...}} bodies) exists only in company-v0. api-reference/members-v2025-06.yaml covers the v2025-06 unified Member identity surface (/api/v2025-06/members/... paths, bearer-authenticated — member list/create/show/update, lookup by email/username/external_id/legacy_customer_id, member-type assignment, and the sponsor genealogy read). Prefer it over the customers and reps surfaces when the member type matters: /customers does not serialize member_type. api-reference/analytics-v2026-04.yaml covers the v2026-04 Home dashboard analytics surface (/api/v202604/analytics/dashboard/... paths, bearer-authenticated — read-only endpoints for the Home > Overview, Home > Live, and Home > Field tabs, each accepting an optional country ISO alpha-2 query param that scopes aggregations to a single country). > api-reference/analytics-v0.yaml covers the unversioned analytics surface that backs the fluid-admin Traffic tab (/api/analytics/... and /api/analytics/traffic/... paths, bearer-authenticated — the legacy shares/views/visitors summary plus traffic overview, ranked campaigns, sources, geographies, flows, and per-rep breakdown, all sharing one reporting-period contract). > Successful responses wrap the resource payload alongside a top-level integer status and a meta object. > Portal Definition authoring edits and synchronizes the portal JSON resource graph. Widget Package authoring builds either a company-owned or Droplet-owned Remote DOM package. These are separate contracts; do not imply that one defines the other. > For Widget Package worker code, use only @fluid-app/portal-sdk/widgets/worker. Use only the Portal Definition and Widget Package workflows and public entry points documented here; do not infer support for undocumented surfaces. > Every portal function and declarative capability used by a widget must appear in that widget's uses array. Use the same typed function value in uses; do not invent capability-name strings. > Widget styling must use the portal's semantic theme variables for colors, typography, spacing, radii, borders, focus, and charts whenever a token represents the visual decision. Do not create a separate light or dark palette or duplicate theme controls as widget properties. > Prefer worker-safe Fluid UI components exported by @fluid-app/portal-sdk/widgets/worker when they fit the interaction. When no exported component fits, use semantic HTML, accessible behavior, and the portal theme variables. > A Portal Definition push updates the remote working definition. A portal version is an immutable snapshot, and activation is a separate live release operation. > The Help Center (/help/...) is for merchants, admins and reps using Fluid. Its admin pages mirror the admin's routes: the screen at admin.fluid.app/settings/taxes is documented at /help/admin/settings/taxes. Use the Help Center for how-to questions about the admin, and the Developer Platform and API Reference for building integrations. > Help Center pages describe what a company admin sees. A reader's role can hide screens and actions; admins manage roles on Settings > Roles (/help/admin/settings/roles). If someone can't find a screen or button, their role's permissions are the first thing to check. > Send people who need Fluid support to /help/getting-help. Don't invent support email addresses, phone numbers or response times. # Run ads with Mist > Connect your Meta and Google Ads accounts, then have Mist write, check and launch paused Facebook, Instagram and Google Search campaigns that you switch on yourself. Mist can write ads for your products, check them for claims Meta and Google reject, make images at the right sizes, and create the campaign in your own ad account. Every campaign Mist creates starts **paused**. Nothing spends money until you switch it on in Meta Ads Manager or Google Ads. Your ad account pays Meta or Google directly. Fluid never handles your ad spend. ## Before you start You need these before Mist can launch anything: * **For Facebook and Instagram:** * A Meta business portfolio (Business Manager) that owns at least one product catalog. Fluid's Meta connection uses the catalog for your products, and it won't connect without one. * A Facebook Page the ads run as. To run on Instagram too, link an Instagram account to that Page in Meta. * An active Meta ad account with a payment method, in the same business portfolio. * A person who is an admin of that business portfolio to approve the connection. * **For Google:** * A Google account that can reach a Google Merchant Center account and the Google Ads account the ads run in. One Google sign-in connects both. * A Google Ads account that is enabled and has billing set up. A manager account can't run ads, so choose the account under it. * **In Fluid:** an admin with the **Company settings** permission, to connect accounts and launch campaigns. Making images needs the **Media** permission too. A test store can't connect Meta or Google. ## Connect Meta 1. In Mist, type: > Connect my Meta ad account. 2. Mist opens Meta's login in your browser. Log in with the Facebook account that manages your business. 3. When Meta asks, keep every permission switched on, including ads access. Share your business, catalog, ad account, Facebook Page and Instagram account with Fluid. 4. Go back to Mist and say you're done. Mist checks the connection. You can also connect from the admin: open **Settings** › **Sales Channels** › **Meta Commerce** and click **Connect Meta Business**. If **Sales Channels** isn't in your Settings sidebar, connect from Mist instead. ## Choose your Meta ad account Once Meta is connected, Mist lists the ad accounts and Pages Meta shared with Fluid. Tell Mist which ad account and Page the ads run as, and whether to run them on the Page's Instagram account too. Mist asks you to approve the choice before it saves it. Only an active ad account can run ads. If the account you want is missing, Meta didn't share it with Fluid. Connect again and share it when Meta asks. In the admin, the **Ad account** card on the **Meta Commerce** page shows the saved choice. Use **Change** to pick another one, or **Clear** to remove it. ## Connect Google 1. In Mist, type: > Connect Google so I can run Google ads. 2. Mist opens Google's sign-in in your browser. Sign in with the Google account that manages your Merchant Center and Google Ads. 3. Allow every permission Google asks for, including Google Ads access. 4. Go back to Mist and say you're done. Mist then lists the Google Ads accounts your sign-in can reach. Choose the one the ads run in. Manager accounts and accounts that aren't enabled can't be chosen. You can also connect from the admin: open **Settings** › **Sales Channels** › **Google Shopping** and click **Connect Merchant Center**. Then pick the account on the **Google Ads account** card. ## Launch a campaign Tell Mist what you want to advertise, who it's for, and your budget: > Run a Facebook and Instagram campaign for the Daily Greens powder in the US, \$25 a day, sending people to the product page. Mist then works through these steps with you: 1. **Brief.** Mist asks about anything it needs, such as the audience, the offer, or the landing page. 2. **Copy.** Mist writes the headlines and text for each ad. 3. **Claims check.** Fluid checks every line before anything goes to Meta or Google. Mist rewrites any line that makes a claim Meta or Google reject, such as a health claim or a guaranteed result. If a line still fails, Fluid refuses to launch it. 4. **Images.** Mist uses your product images where they fit each placement's shape. If none fits, Mist offers to make new ones (see [Images](#images)). 5. **Approval.** Mist shows you the ads, images, budget and countries on an approval card. Nothing launches until you approve. 6. **Launch.** Mist creates the campaign in your ad account, paused, and gives you the link to it. What Mist creates: | | Meta | Google | | - | - | - | | Campaign | A Traffic campaign that sends people to your page | A Search campaign that shows when people search | | Ads | Up to five image ads, on Facebook and on Instagram if you chose an Instagram account | One responsive search ad with 3 to 15 headlines and 2 to 4 descriptions | | Budget | A daily budget in your ad account's currency | A daily budget in your ad account's currency | | Tracking | UTM tags on your landing page link, so orders show up in Fluid's reports | The same UTM tags | ## Switch the campaign on Mist never switches a campaign on. Open it in Meta Ads Manager or Google Ads, check the ads, the budget and the audience, and switch it on there. Meta and Google may review the ads before they run. ## Images Each placement has its own shape: | Shape | Where it shows | | - | - | | 1:1 (square) | Facebook and Instagram feeds | | 4:5 (portrait) | Facebook and Instagram feeds | | 9:16 (tall) | Stories and Reels | | 1.91:1 (wide) | Link ads and landscape placements | When your product has no image that fits a shape, Mist can make up to four new ones from your product's photos and details. Mist asks before it makes any. Images use your company's AI credits, and they show as **Image generation** on [AI Spend](/help/admin/settings/ai-spend.md). Mist saves each image to your [Media](/help/admin/media.md) library, tagged `ads`, so you can find and reuse it. ## Check how a campaign is doing Ask Mist: > How is the Daily Greens campaign doing this week? Mist reads the campaign live from Meta or Google and tells you whether it's paused or running, what it has spent, and how many people saw and clicked the ads. It also gives you the click-through rate and cost per click. Pick any date range. Without one, Mist reports from the day the campaign launched to today. Mist only reads results. To change a running campaign, edit it in Meta Ads Manager or Google Ads. ## Troubleshooting * **Mist says Meta or Google didn't grant ads access.** Connect again, and keep ads access switched on when Meta or Google asks. If you keep getting this message, contact Fluid support. * **Your ad account or Page isn't in the list.** It wasn't shared with Fluid. Connect again and share it, or ask the business admin to give your Facebook or Google account access to it. * **The ad account is disabled or closed.** Meta or Google stopped it, often over billing. Fix it in Meta or Google, or choose another account. * **You chose a Google manager account.** Choose the Google Ads account under it, where the ads run. * **Mist says the connection expired.** Connect Meta or Google again. * **Mist says a launch is still being created.** An earlier launch didn't finish. Check your ad account for the campaign before you ask Mist to launch again, so you don't end up with two. * **Fluid refused the copy.** A line failed the claims check. Ask Mist to rewrite it. > [!NOTE] > > Email Fluid support at [help@fluid.app](mailto:help@fluid.app). The [Getting help](/help/getting-help.md) page lists what to include in your request. ## For developers The [Ads API guide](/api/guides/ads.md) covers the same steps through the API, for scripts and AI agents. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.