> ## 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. # Shipping > Pick how your store calculates shipping: per-variant rates, a flat fee per country, a droplet, or Fluid Rates shipping methods. The **Shipping** screen sets one pricing option for your whole store. If you choose **Fluid Rates**, you set up shipping methods and their rates on the **Shipping Methods** screen. ## Where to find it In the admin, click the **Settings** gear in the top bar. In the Settings sidebar, under **Commerce**, select **Shipping**. ## What's on the screen The **Shipping Pricing Options** card lists four options. You can select only one. The selected option is highlighted and shows a button that opens the screen where you set it up. * **Product-based Rates**: you enter a shipping rate for each product variant in each country it's sold in. Click **View Products** to open your product list. * **Flat Country Rates**: you charge a fixed shipping fee based on the destination country. Click **View Countries** to open the **Countries** screen, where each country has a **Shipping/handling Fee**. See [Countries](/help/admin/settings/countries). * **Use a Droplet**: you connect your shipping calculation through a droplet integration. Click **View Droplets** to open the **Droplets** screen. * **Fluid Rates**: you define your own shipping methods with tiered rates based on price or weight, with pricing by country and state. Click **Manage Shipping Methods** to open the **Shipping Methods** screen. For **Product-based Rates**, open a product and click a variant in its variant table. The variant's pricing table has a row for each country. Enter the rate in the **Shipping** column, then click **Save** at the top of the variant page. The **Shipping Methods** screen lists your methods in a table with **Name**, **Rate Type**, **Currency**, **Rates**, **Priority** and **Status** columns. The **All**, **Active**, **Inactive** and **Draft** tabs filter the list. **Import CSV** and **Add Shipping Method** are at the top of the screen. ## Tasks ### Change how shipping is calculated To switch to **Fluid Rates**, follow [Set up Fluid Rates](#set-up-fluid-rates) instead, so checkout has rates as soon as you save. Under **Shipping Pricing Options**, click the option you want. Click **Save** at the top of the screen. The message **Shipping option updated successfully** appears. If you click the button under the option before you save, you lose your selection. Click the button under the selected option and set it up from there, as described for each option above. ### Set up Fluid Rates Until your company has at least one shipping method, of any status, Fluid calculates shipping the same way as **Product-based Rates**. After that, checkout offers only **Active** methods that have a tier matching the order. If none match, checkout has no shipping option to offer. Add your methods and their rates before you save **Fluid Rates**, so checkout always has a rate to offer. On the **Shipping** screen, select **Fluid Rates** and click **Manage Shipping Methods**. You save **Fluid Rates** in the last step. Click **Add Shipping Method**. Enter a **Name**, such as `Standard Shipping`, and select a **Warehouse**. Both are required. For **Rate Type**, choose **Price-based** or **Weight-based**. If you choose **Weight-based**, also select a **Weight Unit**. You can also set **Currency Code** (`USD` by default), **Delivery Time Estimate**, **Priority (lower = shown first)** and **Status** (**Active** by default, **Inactive** or **Draft**). Click **Save**. In the shipping methods list, click the method you just added. The **Rates** section appears only when you open a saved method. Under **Rates**, click **Add Rate**. Choose a **Country**, or leave **Global (all countries)**. If the country has states, you can choose a **State**, or leave **All states**. Enter **Min** and **Max** for the price or weight range the tier covers, and the shipping **Price** for that range. **Price** is required. Click **Apply**, then repeat for each tier. Each tier for a location must start `0.01` above the previous tier's **Max**. See **Why won't my Fluid Rates tiers save?** below. **Global** tiers apply only while the method has no tiers for a specific country. After you add a tier for any country, checkout ignores the method's **Global** tiers. The method is then offered only for addresses whose state, or whose country under **All states**, has a matching tier. Click **Save changes** next to **Add Rate**. It appears once you have unsaved rate changes, along with a count of them. The **Save** button at the bottom of the panel saves only the method's details and closes the panel. Closing the panel also throws away rates you haven't saved, so click **Save changes** first. Go back to the **Shipping** screen: in the Settings sidebar, under **Commerce**, select **Shipping**. Select **Fluid Rates** and click **Save**. ### Import methods and rates from a CSV To create many methods and rates at once, import them from a CSV file. New weight-based methods that the import creates use pounds. If your file's weights are in another unit, open each new method after the import, set **Weight Unit**, and click **Save**. On the **Shipping Methods** screen, click **Import CSV**. The **Import Shipping Methods** window lists the required columns. Click **Download sample CSV** for an example file. Click **Select File**, or drag a CSV file onto the window. This step appears if your file is missing any of these columns: `warehouse`, `rate_type`, `currency_code`, `status` or `delivery_estimate`. The window asks you to set a default for each missing column. If your file has no warehouse column, select a **Warehouse**. It's required. **Rate Type** starts at **Weight-based**. Click **Continue**. This step appears only if Fluid corrected values in your file, such as letter case or extra spaces. Click **Accept Corrections**, or click **Reject & Re-upload** to choose another file. The preview marks each method **New** or **Replace rates** and lists any errors. Rows with errors aren't imported, and neither is a weight-based method whose tiers have errors. To fix errors, correct your file and click **Replace** to choose it again. Click the import button. It shows the number of methods, for example **Import 3 Methods**. When the import finishes, click **Close**. The import matches methods by name, ignoring capitalization. If a method in the file already exists, the import replaces its rates for each location in the file and keeps its rates for other locations. It doesn't change the method's other settings. ### Edit a shipping method On the **Shipping Methods** screen, click the method. The **Edit Shipping Method** panel opens. To edit a rate, click its pencil icon, change it, and click the check mark icon. To remove a rate, click its trash icon. Until you save, a saved rate you removed stays in the list with an undo icon that brings it back. To drop all unsaved rate changes, click **Discard**. Click **Save changes** next to **Add Rate**. Change the method's details, such as **Name** or **Status**, and click **Save** at the bottom of the panel. You can't change a method's **Warehouse** after you create it. Picking another warehouse in the panel doesn't change it. To use a different warehouse, add a new method. ### Delete a shipping method Deleting a method also deletes all of its rates, and you can't undo it. To take a method out of checkout but keep it, set its **Status** to **Inactive** instead. On the **Shipping Methods** screen, open the three-dot menu at the end of the method's row and click **Delete**. In the **Delete shipping method?** dialog, click **Delete**. ## Tips Each permission below is a switch in an area on your role's **Permissions** tab. * **Orders**: **Access order settings and configuration (Checkout, Shipping, Taxes)** shows **Shipping** in the Settings sidebar and lets you open this screen and the **Shipping Methods** screen. * **Companies**: **View company details** is needed to load this screen. Without it, the screen doesn't open. * **Companies**: **Edit company details** is needed to save a shipping option. * **Orders**: **View orders list, order details, and order history** is needed to see your shipping methods. * **Orders**: **Edit order details, add notes, and update status** is needed to add, edit, import or delete methods and rates. **Orders** is in the **Commerce** card and **Companies** is in the **Settings** card. An admin who manages roles can turn these on. They open your role on the **Roles** screen, open the card on the **Permissions** tab, and click the area to see its switches. See [Roles](/help/admin/settings/roles). **Save** stays grayed out until you select an option that's different from the saved one. It's also unavailable while the screen is loading or saving. Tiers for the same location (**Global**, a country under **All states**, or one state) must be continuous. Each tier's **Min** must be exactly `0.01` above the previous tier's **Max**, for example `0` to `49.99`, then `50` to `99.99`. If two tiers overlap or leave a gap, an error names the location and the value the next tier should start at. Each tier's **Max** must also be greater than its **Min**. For a **Weight-based** method, each location's first tier must start at `0`. If a tier breaks one of these rules, an error appears above the rates and Fluid doesn't save any of your rate changes. When you click **Add Rate**, **Min** starts `0.01` above the highest **Max** among the method's rates, or at `0` if it has none. If you're starting tiers for a different country or state, change **Min** to where that location's first tier begins. For a **Weight-based** method, that's `0`. Adding tiers for a specific country to a method that has **Global** tiers means checkout stops using its **Global** tiers. See the note in [Set up Fluid Rates](#set-up-fluid-rates). The **Warehouse** list shows your company's warehouses. If it's empty, add a warehouse first. See [Warehouses](/help/admin/settings/warehouses). The list is also empty if your role can't view warehouses. In that case, an error that starts with **Failed to load warehouses** appears when you open the **Shipping Methods** screen. An admin who manages roles can give your role **View only** or **Full access** to **Warehouses**, in the **Settings** card. See [Roles](/help/admin/settings/roles). ## Related pages * [Settings](/help/admin/settings) * [Countries](/help/admin/settings/countries) * [Warehouses](/help/admin/settings/warehouses) * [Roles](/help/admin/settings/roles) * [Droplets](/concepts/droplets)