> ## 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. The merchant must open the emailed sign-in link and create an API token before authenticated calls are possible. > 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. /api/company/v1 and /api/v1/... paths are documented in no spec here and must never be used (/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. > Navigation menu management is documented in themes/navigation-menus. These unversioned admin endpoints (/api/menus and nested menu_items) are verified against the implementation but are not yet in the synced OpenAPI specs. Use that reference for menu payloads and its flat page/per_page pagination; missing spec coverage does not make these endpoints unavailable. > 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. # Tax > Choose how Fluid calculates tax on orders, connect your own Avalara account, and set each country's tax details. The Tax screen holds your company's tax setup. You choose one tax mode for the whole company, then set each country's details, such as tax-inclusive pricing and business tax ID. ## Where to find it In the admin, click the **Settings** gear in the top bar. In the Settings sidebar, under **Commerce**, select **Taxes**. ## What's on the screen The screen has two cards: **Tax Calculation**, which sets one tax mode for your whole company, and **Per-Country Tax Configuration**, which lists your countries. ### Tax Calculation Choose one tax mode: * **Droplet**: connect your existing tax provider account through a droplet. When it's selected, an **Explore Available Droplets** button appears and opens the **Droplets** page. * **Custom Tax Integration**: use callbacks to connect a tax provider that isn't available as a droplet. When it's selected, a **Configure Callbacks** button appears and opens the [Callbacks](/help/admin/settings/callbacks) screen. * **Fluid's Tax Solution**: use Fluid's pre-configured tax settings, which you can customize per country. When it's selected, an **Edit Tax Settings per Country** button appears and opens the [Countries](/help/admin/settings/countries) screen. The Countries screen's only tax field is **Business tax ID number**. Edit the other country tax settings in the **Per-Country Tax Configuration** card on this screen. * **Avalara**: use your own Avalara (AvaTax) account through Fluid's built-in integration. When it's selected, a credentials form appears under it. * **Free Tax**: charge no tax on any order, regardless of country or cart value. * **Per Country**: set a different tax mode for each country. Clicking a mode doesn't change your settings yet. After you click one, a **Save** button appears at the top of the page. The new mode takes effect when you click **Save**. ### Avalara credentials When **Avalara** is selected, the form under it stores your Avalara account credentials. You can keep one set for each environment: * **Production** and **Sandbox** tabs: choose which environment you're editing. The environment Fluid uses to calculate tax has an **Active** badge. * **Avalara username** and **Avalara password**: your Avalara account sign-in. On a saved environment, leave these unchanged to keep the stored values. * **Company code (optional)**: your AvaTax company code. * **Save Credentials**: saves the credentials for the selected tab. This button works separately from the page's **Save** button. * **Use this environment**: appears on a saved environment that isn't active. Click it to make that environment the active one. * **Remove credentials**: appears on a saved environment. Click it and confirm to delete the selected tab's credentials. The first environment you save becomes the active one. If **Sandbox** is active, Fluid calculates tax against Avalara's sandbox, and the form reminds you to activate **Production** before you take real orders. ### Per-Country Tax Configuration The table lists your company's countries: * **Country**: the country's flag and name. Your default country has a **Default** badge. * **Tax Mode**: the country's own tax mode. This column appears only in **Per Country** mode. * **Tax Business ID**: the country's business tax ID, or a dash if none is set. * **Last Updated**: when the country's settings last changed, for example **Today** or **3 days ago**. Use the search box to find a country by name. Click a row, or choose **Edit Tax Settings** from its actions menu, to open that country's tax settings. The **Tax Mode** column and the **Bulk Settings Update** button appear only after you save **Per Country** as your tax mode. Before you switch, read the warning under [Choose your tax mode](#choose-your-tax-mode). ### Country tax settings The country's tax settings open in a panel titled with the country's name, for example **Canada Tax Settings**. In **Per Country** mode, you choose the country's own tax mode in the panel. In any other mode, every country uses the company-wide tax mode, and the panel edits only the country's tax details. Some fields depend on your tax mode: * **Tax Mode**: appears only in **Per Country** mode. Choose **Tax Droplet**, **Custom Tax Integration**, **Fluid's Tax Solution**, **Avalara** or **Free Tax** for this country. * For **Tax Droplet**, pick one of your active tax droplets. For **Custom Tax Integration**, pick one of your custom tax callbacks, listed by URL. * If you have none, the panel says so and offers **Explore Available Droplets** or **Configure Callbacks**. The panel also reminds you to set the integration's country filters in Droplets or Callbacks settings. The [Callbacks](/help/admin/settings/callbacks#the-callback-panel) screen has no country filter field. * For **Avalara**, the same credentials form appears. An Avalara environment must be active before you can save. * **Tax Strategy**: appears when the country uses **Fluid's Tax Solution**. The panel lists only the strategies available for the country. If you haven't chosen one, the panel pre-selects the first. * **Use Fluid's tax calculation settings**: Fluid calculates tax automatically from your business location, the customer's address and applicable tax laws. * **Use Fluid's flat rate for this country**: Fluid calculates tax from its built-in tax table. * **Tax Calculator**: replaces **Tax Strategy** when your company-wide mode is **Droplet**, **Custom Tax Integration**, **Avalara** or **Free Tax**. It's a note that says how tax is calculated for every country. * **Commit transactions to Avalara**: appears only for the United States and Canada, when Avalara calculates tax for the country. * Turn it on to file each paid order shipping to this country as a committed sales invoice on your Avalara account. These are real tax documents on your account. * Fluid voids or returns the invoice when the order is canceled or fully refunded. * To turn it on, your **Production** environment must be active, with a **Company code** saved on it. These appear in every tax mode: * **Tax-Inclusive Pricing**: turn this on to display prices with tax included, as is common with VAT. When it's on, the panel shows: * **Tax rate**: the country's standard rate. You can't edit it. * **Tax name**: the tax's name, such as GST, VAT or Sales Tax. If the country has a default tax name, the field starts with it. If it doesn't, **Tax name** is required. * **Business tax ID number**: your tax registration number for this country, such as a VAT, GST or EIN number. You can also edit it on the **Countries** screen. * **Legal Disclaimer**: a reminder that business laws vary by country, and that your business must comply with this country's requirements. For some countries, it adds country-specific legal information. For others, it suggests you consult local legal experts. * **Require Gaiyo Shomen in enrollment flows**: a checkbox that appears only for Japan. The panel ends with **Cancel** and **Save**. ## Choose your tax mode Saving a new company-wide mode also changes your countries: * **Per Country**: each country uses its own **Tax Mode**, which may not match the mode you were using. Check the **Tax Mode** column right after you save, and use **Bulk Settings Update** or each country's settings to set the mode you want. * **Fluid's Tax Solution**: Fluid sets each country's **Tax Strategy** to **Use Fluid's tax calculation settings**, including countries that used **Use Fluid's flat rate for this country**. * **Droplet**, **Custom Tax Integration**, **Avalara** or **Free Tax**: Fluid clears each country's **Tax Strategy**. Any mode other than **Per Country** also clears the droplet or callback chosen in each country's settings. To use Avalara, follow [Connect your Avalara account](#connect-your-avalara-account) instead. If you're switching to **Droplet** or **Custom Tax Integration**, set up the integration first. Click **Droplet**, then **Explore Available Droplets**, and install a tax droplet. Or click **Custom Tax Integration**, then **Configure Callbacks**, and set up your tax callback on the [Callbacks](/help/admin/settings/callbacks) screen. Either button leaves the Tax screen without saving the mode you clicked. On the Tax screen (**Taxes** in the Settings sidebar), click the mode you want in the **Tax Calculation** card. Click **Save** at the top of the page. You see **Tax settings updated successfully**. ## Connect your Avalara account In the **Tax Calculation** card, click **Avalara**. The credentials form appears under it. Click the **Production** or **Sandbox** tab. Enter your **Avalara username** and **Avalara password**. If your AvaTax account uses a company code, enter it in **Company code (optional)**. You need a company code on your **Production** environment to use **Commit transactions to Avalara**. Click **Save Credentials**. You see **Avalara credentials saved**. If this is the first environment you've saved, it becomes the active one. Click **Save** at the top of the page. **Save** stays unavailable until an Avalara environment is active. To switch environments, open the other tab and click **Use this environment**. ## Edit a country's tax settings In the **Per-Country Tax Configuration** card, click the country's row, or choose **Edit Tax Settings** from its actions menu. Update the fields you need. In **Per Country** mode, choose the country's **Tax Mode**, and pick a droplet or callback if the mode needs one. Click **Save**. You see **Country tax settings updated**. **Save** stays unavailable while a required choice is missing, such as a tax integration or a required **Tax name**. ## Update several countries at once In **Per Country** mode, click **Bulk Settings Update** in the **Per-Country Tax Configuration** card. The **Bulk Tax Settings Update** panel opens. Under **Tax Mode**, choose **Tax Droplet**, **Custom Tax Integration**, **Fluid's Tax Solution**, **Avalara** or **Free Tax**. **Fluid's Tax Solution** is selected when the panel opens. For **Tax Droplet** or **Custom Tax Integration**, also pick the integration. For **Avalara**, the credentials form appears, and an environment must be active. Under **Select Countries**, check each country to update. Use the search box to filter the list. **Select All** checks every country in the filtered list, or unchecks them if they're all checked. The heading shows how many countries you've selected. Click **Apply**. You see **Bulk tax settings updated**. A bulk update changes the tax mode, plus the integration for **Tax Droplet** or **Custom Tax Integration**. It doesn't change a country's inclusive pricing, tax name or business tax ID. Moving a country off **Fluid's Tax Solution** clears its **Tax Strategy**. ## FAQ Different parts of this screen need different permissions on your role: * **Company-wide tax mode**: your role needs **Access order settings and configuration (Checkout, Shipping, Taxes)** under **Orders**, and **Edit company details** under **Companies**. Without the first, no **Save** button appears for the tax mode. Without the second, saving shows **Error updating tax settings**. * **Country tax settings**: your role needs **Edit company country settings** under **Company Countries**. Without it, a country's panel has no **Save** button. * **Avalara credentials**: your role needs **Edit company details** under **Companies**. Without it, the form says **You do not have permission to change Avalara credentials**. In the **Tax Calculation** card, the Avalara fields are also unavailable without **Access order settings and configuration (Checkout, Shipping, Taxes)**. **Orders** is in the **Commerce** card of your role's **Permissions** tab, and **Companies** and **Company Countries** are in the **Settings** card. Ask an admin who manages roles to update your role. See [Roles](/help/admin/settings/roles). You can't remove the active environment's credentials while **Avalara** is your company-wide tax mode, or while any country's own **Tax Mode** is **Avalara**. If you try, you see **Avalara is the selected tax provider; select another provider before removing the active credentials**. Each country keeps its own **Tax Mode** when you change the company-wide mode. You can see it in the **Tax Mode** column only after you save **Per Country**, so read the warning under [Choose your tax mode](#choose-your-tax-mode) first. If you'd rather not switch modes, contact support. 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. To change the active environment's password, you don't need to remove its credentials. Open its tab, enter the new password and click **Save Credentials**. You can always remove an environment that isn't active. If you remove the active environment and the other one has saved credentials, the other one becomes active. While any country that uses Avalara has **Commit transactions to Avalara** turned on, you can't switch to the other environment. Invoices already filed stay on the Avalara account of the environment they were filed in. If you need to switch, contact support before you turn off **Commit transactions to Avalara**. 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. ## Related pages * [Settings](/help/admin/settings) * [Countries](/help/admin/settings/countries) * [Callbacks](/help/admin/settings/callbacks) * [Roles](/help/admin/settings/roles) * [About droplets](/concepts/droplets)