> ## 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 <token>; 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. The merchant must open the emailed sign-in link and create an API token before authenticated calls are possible.
> 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 where a spec documents it — in practice the unversioned company-v0 admin surface; every versioned surface uses cursor pagination.
> 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 — 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.

# Troubleshooting

> Find the fix for common problems with signing in, missing screens and buttons, orders and payments, your storefront, the mobile app and Mist.

Find your problem below, then follow the link to the guide that covers it in full. If nothing here matches, [contact support](/help/getting-help#contact-support).

## Signing in and access

<AccordionGroup>
  <Accordion title="I can't sign in. What should I do?" id="cant-sign-in">
    [Contact support](/help/getting-help#contact-support) and include the details that page lists, such as your sign-in email address and your company name. If the problem is on the sign-in page, describe what you see instead of sending its address.

    Never include the code or sign-in link from a sign-in email, or any password, in a support request.
  </Accordion>

  <Accordion title="Why does the mobile app show an error when I sign in?" id="app-sign-in-error">
    If a message such as **There was an error signing in** appears, the app takes you back to the first screen. Tap **Sign in with email** to try again. If the sign-in page doesn't load, tap **Back** at the top and try again. See [Trouble signing in](/help/mobile/settings#trouble-signing-in).
  </Accordion>

  <Accordion title="Why is the app's sign-in screen in a different language?" id="app-sign-in-language">
    The sign-in screens follow your phone's language when the app supports it, not the language you chose on the Dashboard. See [Trouble signing in](/help/mobile/settings#trouble-signing-in).
  </Accordion>

  <Accordion title="Why didn't my Mist sign-in code work?" id="mist-code-failed">
    The code expires after a few minutes. Click **Resend code** to get a new one, and make sure you entered the email address you use for Fluid. See [Download Mist](/help/mist/download#code-failed).
  </Accordion>

  <Accordion title="How do I change the email address I sign in with?" id="change-sign-in-email">
    Contact support. In the admin portal, the **Email** field on your **Profile** page is read-only because it's your sign-in address, and a new address must be verified before the change takes effect. See [Getting help](/help/getting-help#change-sign-in-email).
  </Accordion>

  <Accordion title="I'm in the wrong company. How do I switch?" id="wrong-company">
    If you belong to more than one company, you can switch. In the mobile app, tap **Organization** near the top of the Dashboard, then choose a company. In Mist, click the company name in the title bar. See [Switch organizations](/help/mobile/settings#switch-organizations) and [Switch company](/help/mist/download#switch-company).
  </Accordion>
</AccordionGroup>

## A screen, button or card is missing or grayed out

In the admin, your role controls what you can see and do. If a screen or an action is missing, ask an admin who manages roles to check your role.

<AccordionGroup>
  <Accordion title="Why can't I see a screen in the admin?" id="missing-screen">
    Ask an admin who manages roles to check that your role can view it. See [Settings](/help/admin/settings#missing-settings-screen) and [Roles](/help/admin/settings/roles).
  </Accordion>

  <Accordion title="Why are some buttons and cards grayed out or missing?" id="buttons-grayed-out">
    Your role's access decides which actions you get. On **Getting Started**, for example, a role with **View only** for **Getting Started** sees **Connect Now** and some cards grayed out, and a card for another area appears only if your role can view that area. Ask an admin who manages roles to update your role. See [Getting Started](/help/admin/getting-started#grayed-out).
  </Accordion>

  <Accordion title="Why don't I see Save, Publish or Customize in the Page Editor?" id="no-save-publish">
    Your role doesn't have the **Theme** switch **Customize and edit theme settings**. An admin who manages roles can turn it on in the role's **Permissions** tab, in the **Content & Website** card. See [Page Editor](/help/admin/page-editor#no-save-publish).
  </Accordion>

  <Accordion title="Why can't I see Analytics or Home?" id="no-analytics">
    Your role needs **View only** or **Full access** for **Payment Reports**. Without it, the **Analytics** group doesn't appear in the sidebar. See [Home](/help/admin/home#no-analytics).
  </Accordion>
</AccordionGroup>

## Orders, checkout and payments

<AccordionGroup>
  <Accordion title="What should I do about payment processing errors?" id="payment-processing-errors">
    **Processing error** declines come from the gateway or the platform, not from your shoppers' cards. If they keep happening, contact Fluid support. See [Payment performance](/help/admin/payments/performance#processing-errors).
  </Accordion>

  <Accordion title="Why can't I refund an order?" id="cannot-refund">
    Hover over the grayed-out **Refund** button to see the reason. If **Refund** doesn't appear but **Cancel Order** does, cancel the order instead. See [Orders](/help/admin/orders#cannot-refund).
  </Accordion>

  <Accordion title="How do I refund a subscription order?" id="refund-subscription-order">
    Refund it from its order, like any other order. Open the order and click **Refund**. See [Orders](/help/admin/orders#refund-subscription-order).
  </Accordion>

  <Accordion title="Why can't I fulfill an order?" id="cannot-fulfill">
    Archived and cancelled orders can't be fulfilled. An order on hold can't be fulfilled until you remove the hold. See [Fulfill items](/help/admin/orders#fulfill-items).
  </Accordion>

  <Accordion title="Why can't I save my tax changes?" id="cannot-save-tax">
    Different parts of the **Tax** screen need different permissions on your role. Ask an admin who manages roles to update your role. See [Tax](/help/admin/settings/taxes#cant-save-tax-settings).
  </Accordion>

  <Accordion title="Why won't my enrollment pack save with a subscription?" id="enrollment-pack-wont-save">
    Choose a plan from **Select plan** next to the subscription product. A subscription product without a plan can't be saved. See [Enrollments](/help/admin/enrollments#subscription-needs-plan).
  </Accordion>

  <Accordion title="Why doesn't a promo code work for a shopper?" id="promo-code-not-working">
    Check the code against its rules, such as its status, active dates, use limits and eligibility, and whether it combines with the other codes in the cart. If everything matches and the code still fails, contact support. See [Promo Codes](/help/admin/promo-codes#code-not-working).
  </Accordion>

  <Accordion title="Why don't shoppers see my form at checkout?" id="form-not-showing">
    Check that the form is **Active**, that its **Form type** is **Post Purchase**, and that its countries include the cart's country. Regular checkouts never show forms, only enrollment checkouts. See [Forms](/help/admin/forms#form-not-showing).
  </Accordion>
</AccordionGroup>

## Your storefront or website

<AccordionGroup>
  <Accordion title="How do I clear my storefront's cache?" id="clear-storefront-cache">
    On the **Themes** screen, click the three-dot button at the top of the screen and choose **Clear Cache**. It clears the cache for every page of your storefront. See [Themes](/help/admin/themes#clear-the-cache).
  </Accordion>

  <Accordion title="Why does Clear Cache fail?" id="clear-cache-fails">
    **Clear Cache** needs the **Developer** switch that starts with **Manage webhooks and API configuration**. Without it, you see **Failed to clear cache**. See [Page Editor](/help/admin/page-editor#clear-cache).
  </Accordion>

  <Accordion title="Why is View your site grayed out?" id="view-your-site-grayed-out">
    Your company's signup email isn't confirmed yet. Confirm the email to turn on **View your site** and your storefront previews. See [Themes](/help/admin/themes#view-your-site-disabled).
  </Accordion>

  <Accordion title="How long does domain setup take?" id="domain-setup-time">
    The ownership check can take a few minutes, and the **Connect this domain** button estimates about 5 minutes to connect. See [Domains](/help/admin/settings/domains#setup-time).
  </Accordion>

  <Accordion title="What should I do if domain setup fails?" id="domain-setup-failed">
    The domain's status changes to **Setup Failed**, and the setup card explains what went wrong, for example a CNAME record that doesn't match. **Check Status** runs the check again, and some failures clear on a retry. If it keeps failing, contact support. See [Domains](/help/admin/settings/domains#setup-failed).
  </Accordion>
</AccordionGroup>

## The mobile app

<AccordionGroup>
  <Accordion title="Why does a screen in the app show out-of-date information?" id="app-out-of-date">
    Clear the app's cache. It makes the app load your data again, and you stay signed in. On the Dashboard, tap **General Information**, then **Clear Cache**. See [Clear the cache](/help/mobile/settings#clear-the-cache).
  </Accordion>

  <Accordion title="How do I update the app?" id="update-the-app">
    When a new version is ready, an **Update Available** banner appears at the top of **Home**. Tap the banner to update. See [Update the app](/help/mobile/settings#update-the-app).
  </Accordion>

  <Accordion title="Why can't I reply in a conversation?" id="cannot-reply">
    You can't send a message from the app when the conversation is an SMS or email conversation, archived, closed or a broadcast-only channel, or when it shows **Only admins can send messages.** See [Messaging](/help/mobile/messaging#cannot-reply-in-conversation).
  </Accordion>

  <Accordion title="Why can't I find a tab or feature in the app?" id="cant-find-a-tab">
    Your company chooses which features and tabs appear in its app, what the tabs are called and their order. If your app has more than five tabs, the rest are under **More**, the three-lines icon at the end of the tab bar. See [Getting around the app](/help/mobile/getting-around#cant-find-a-tab) and [Mobile app](/help/mobile).
  </Accordion>

  <Accordion title="Why doesn't the Catch Up widget open?" id="catch-up-widget-wont-open">
    The widget opens only when you have catch-ups. When you have none, it shows "You're all caught up." See [Getting around the app](/help/mobile/getting-around#catch-up-widget-wont-open).
  </Accordion>

  <Accordion title="Why don't I see MySite on the Dashboard?" id="no-mysite-card">
    The **MySite** card shows only if you have a MySite. If you think you should have one, tap **Get Help** on the Dashboard to contact support. See [MySite](/help/mobile/my-site#no-mysite-card).
  </Accordion>

  <Accordion title="How do I get back contacts I deleted?" id="restore-deleted-contacts">
    If they're still in your phone's contacts, run a force sync from **Import Contacts**. Your phone's contacts sync again, including ones you deleted from the app. See [Contacts](/help/mobile/contacts#restore-deleted-phone-contacts).
  </Accordion>

  <Accordion title="I set up a Home page or navigation in the admin. Why don't members see it?" id="members-dont-see-app-changes">
    Check that it's **Active** and that the members match every access rule on it. Saving another active page or navigation with exactly the same rules unpublishes it. See [Home Pages](/help/admin/mobile/home#members-dont-see-page) and [Navigation](/help/admin/mobile/navigation#members-dont-see-navigation).
  </Accordion>

  <Accordion title="What should I include when I report a problem with the app?" id="report-an-app-problem">
    Include your device model, operating system version and app version, how often the problem happens, and what you already tried. To copy your app details, tap your picture or initials at the top of the app's home screen, then **General Information**, then **App Info**, then **Copy**. See [Report a mobile app issue](/help/getting-help#report-a-mobile-app-issue).
  </Accordion>
</AccordionGroup>

## Mist

<AccordionGroup>
  <Accordion title="Why did Mist stop answering?" id="mist-out-of-credits">
    Your company may be out of AI credits or have reached its AI spend limit. Mist tells you why, and an admin can check **Billing** in the admin. See [Model selection](/help/mist/models#out-of-credits) and [Billing](/help/admin/settings/billing).
  </Accordion>

  <Accordion title="Why don't I see my company's Fluid data in Mist?" id="mist-no-fluid-data">
    An admin has to turn on the Fluid database on the **Databases** screen, and your role has to be one that can query reporting databases. See [Databases in Mist](/help/mist/databases#no-fluid-data).
  </Accordion>

  <Accordion title="What happens if creating a Mist app fails?" id="mist-app-create-failed">
    You see **Failed to create mist**, with the reason when one is available. The panel stays open with your entries, so you can fix them and click **Create** again. See [Mist Apps](/help/admin/settings/mist-apps#create-failed).
  </Accordion>

  <Accordion title="My Mist app won't publish or keeps crashing. Where do I start?" id="mist-app-problems">
    Start with the app's logs. Most problems show up there first. See [Troubleshoot a Mist app](/mist-apps/troubleshooting).
  </Accordion>
</AccordionGroup>

## Still stuck

<Info>
  Email Fluid support at [help@fluid.app](mailto:help@fluid.app). The [Getting help](/help/getting-help) page lists what to include in your request.
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.