> ## 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. # Alternative Payment Accounts > Connect PayPal, add other non-card payment accounts, and choose the countries where each one is offered at checkout. **APM** (alternative payment methods) in Settings opens the **Alternative Payment Accounts** screen. Here you manage your company's non-card payment accounts, such as PayPal. ## Where to find it In the admin, click the **Settings** gear in the top bar. In the Settings sidebar, under **Payments**, select **APM**. ## What's on the screen The top bar holds the **Add Payment Account** button. The banner below it mentions tax calculations, but you set up tax on [Taxes](/help/admin/settings/taxes), not here. Card payment gateways have their own **Gateways** screen in the same Settings group. The **Alternative Payment Accounts** card has an **Onboard PayPal Merchant** button next to its heading and a table of your accounts. The search box above the table matches an account's **Reporting Name** (the name used in CSV exports, event logs, and integrations) or payment type, not the **Display Name** shown in the table. The **Sort By** menu sorts by **Name**, or by **Country** (how many countries an account has), in **Ascending** or **Descending** order. | Column | What it shows | | - | - | | **Icon** | The payment type's logo. Types without their own logo show a generic Fluid Pay logo. | | **Name** | The account's display name. A PayPal account whose PayPal setup isn't verified yet also shows a **Setup Required** badge. | | **Status** | **Active** or **Inactive**. | | **Type** | **Production** or **Sandbox**. | | **Country** | The first two countries where the account is available, plus a count of any others, or a dash if none are set. | | **Subscriptions** | **Supported** or **Not Supported**, depending on whether the payment type supports subscriptions. | Click a row to edit that account. The three-dot menu at the end of each row has **Edit** and **Delete**. What you can do here depends on your role. Without APM permissions, **APM** doesn't appear in the Settings sidebar. Depending on your permissions, you may also not see **Add Payment Account**, **Onboard PayPal Merchant**, **Edit**, or **Delete**. An admin can grant these on [Roles](/help/admin/settings/roles), on the role's **Permissions** tab, under **Settings** › **APM**. To connect PayPal or check a PayPal account's setup, the role also needs the **PayPal** permission, under **Commerce** › **PayPal**. ## Connect a PayPal account Each click on **Onboard PayPal Merchant** adds a new, inactive PayPal account to the table, even if you don't finish in PayPal. Its name is `Paypal` followed by the date and time. To remove an unfinished account, open its three-dot menu and click **Delete**. Click **Onboard PayPal Merchant**. The button reads **Redirecting to PayPal...** while Fluid prepares the link, and then PayPal opens. Complete the steps PayPal shows you. When PayPal sends you back, the admin shows **Checking Status...**, then **PayPal Connected!**, and a moment later returns you to APM with the message **PayPal account is ready!** You see this even if the new account stays off, as described below. If PayPal reports a problem, you see **Setup Incomplete** and the reason. Follow the instructions in the message: * If you fixed something in PayPal, click **Retry Verification**. * If the message tells you to go through onboarding again, click **Back to Payments**, and then click **Onboard PayPal Merchant** to start again. * If the reason is **Merchant ID not found**, see [What does Setup Required mean?](#setup-required). To go back to APM instead, click **Back to Payments**. Before you save a PayPal account you connected with **Onboard PayPal Merchant**, make sure **Sandbox Mode** is off. When setup completes, Fluid turns the account on and makes it available in all of your company's countries, but only if it's your company's first PayPal account. If your company has had a PayPal account before, even an unfinished one, the new account stays off and has no countries. To use it, [turn it on](#turn-on-a-paypal-account-that-stayed-off). For a first account, Fluid also sets up a PayPal card gateway. If you don't already have one, Fluid creates one named **PayPal Credit Card Gateway**, and it appears on the **Gateways** screen. You can rename a connected account by editing its **Display Name** and **Reporting Name**. ### Turn on a PayPal account that stayed off Wait until the **Setup Required** badge next to the account is gone. See [What does Setup Required mean?](#setup-required). Click the account's row. The **Edit Payment Account** panel opens. Under **Available Countries**, select the countries where you want to offer the account. Turn on **Active**. Turn off **Sandbox Mode**. Click **Save Changes**. Only one active account of each payment type can serve a country. If another active account of the same type, such as an earlier PayPal account, already serves any of the countries you select, Fluid won't save the change. Turn that other account off, or remove the overlapping countries from one of the two accounts, and then save again. ## Add a payment account Click **Add Payment Account**. The **Add Payment Account** panel opens. Enter a **Display Name**. The admin dashboard and storefront show this name. Enter a **Reporting Name**. CSV exports, event logs, and integrations use this name. Both are required. Select a **Payment Type**. The list shows non-card payment types only. To use a payment method from an installed droplet, select **Droplet**. You can't change the payment type after you create the account. To use a different payment type later, add a new account. Under **Available Countries**, select at least one country. The list shows the countries your company sells in that the payment type supports. If you change the payment type, the form clears your country selection. Enter the credentials and any other fields that appear for the payment type. Required fields have a red asterisk. See [Fields that depend on the payment type](#fields-that-depend-on-the-payment-type). **Active** is off by default for a new account. Turn it on to offer the account at checkout. Checkout offers an account only while it's active, and only in its **Available Countries**. If another active account of the same payment type already serves one of the countries you selected, Fluid won't save the account while **Active** is on. Turn the other account off, or remove the overlapping countries. Click **Add Account**. A message confirms that Fluid created the account, and the account appears in the table. If something is missing, the panel shows an error under the field, such as **At least one country must be selected**. ### Fields that depend on the payment type | Field | When it appears | | - | - | | Credential fields | When the payment type needs credentials. Each payment type sets its own field names. | | **PayPal Email** | PayPal accounts. PayPal onboarding fills it in. Enter it yourself if you set up the credentials manually. | | **Apple Pay Enabled** | PayPal accounts. When it's on, **Decrypted Apple Pay Flow** and more Apple Pay fields appear. | | **Droplet** | When **Payment Type** is **Droplet**. Select an installed payments droplet. If none is installed, you see **No Payments Droplets installed.** and an **Install one first** link. | | **Auto-assign to cart** | When **Payment Type** is **Droplet**. It's on by default. | | **Sandbox Mode** or **Test Only** | Payment types that have a sandbox or test mode. PayPal shows **Sandbox Mode**. If a type has both, they switch together. An account saved with either on shows **Sandbox** in the **Type** column. | | **Require notification signature** | Payment types whose provider signs its payment notifications. It's on by default for a new account. | ## Edit a payment account Click the account's row, or open the three-dot menu at the end of the row and click **Edit**. The **Edit Payment Account** panel opens. Change the fields you need. Saved credentials appear masked. Clicking a masked field clears it. Leave it empty to keep the saved value, or enter the whole new value to replace it. For a PayPal account you connected with **Onboard PayPal Merchant**, turn off **Sandbox Mode** before you save. Click **Save Changes**. ## Delete a payment account Open the three-dot menu at the end of the account's row and click **Delete**. In the **Delete payment account?** dialog, click **Delete**. This can't be undone. ## FAQ It appears next to a PayPal account whose PayPal setup isn't verified yet. Click **Setup Required** to check the account's status with PayPal again. If the check fails, you see **Setup Incomplete** and the reason, as described in [Connect a PayPal account](#connect-a-paypal-account). **Merchant ID not found** means Fluid hasn't received the account's PayPal merchant ID yet. If you finished the PayPal steps, click **Setup Required** again later. If you didn't finish them, click **Onboard PayPal Merchant** to start again, and delete the unfinished account. The new account stays off until you [turn it on](#turn-on-a-paypal-account-that-stayed-off). The **Edit Payment Account** panel shows this warning when PayPal reports that Fluid no longer has permission to use the PayPal account. Fluid turns the account off, and the table shows **Setup Required** next to it. To use PayPal again, click **Onboard PayPal Merchant** and connect the account again. The new account stays off until you [turn it on](#turn-on-a-paypal-account-that-stayed-off). You can delete the old account. Until you choose a **Payment Type**, the field shows **Select an integration to filter by available countries.** If it shows **No countries available for this integration.**, that payment type doesn't support any of the countries your company sells in. You manage your company's countries on [Countries](/help/admin/settings/countries). ## Related pages * [Settings](/help/admin/settings) * [Countries](/help/admin/settings/countries) * [Roles](/help/admin/settings/roles) * [Taxes](/help/admin/settings/taxes) * [Droplets](/concepts/droplets)