> ## 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. > 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. # Payment performance > See how many of your payments are approved, why the rest are declined, and which payment accounts, card brands, methods and countries decline the most. Use the **Payment performance** screen to see how your payments went through over a date range. It shows your approval rates, why payments were declined, what you can do about each cause, and where declines happen. ## Where to find it In the admin sidebar, open **Payments** and select **Performance**. It's the first item in the **Payments** group. To open the screen, your role needs **View only** or **Full access** for **Payment Reports**. On the [Roles](/help/admin/settings/roles) screen, **Payment Reports** is in the **Commerce** card. Open the card and set access from the **Payment Reports** area's menu. The same permission opens **Home**, **Transactions** and **Subscription Billing**. ## What's on the screen The page header reads **Payment performance**. Below it, a row of filters controls every panel on the screen, so all the numbers you see describe the same payments. ### Filters * **Date range**: **Yesterday**, **Last 7 days**, **Last 30 days** (the default), **Last 90 days**, or **Custom range**. **Last 7 days**, **Last 30 days** and **Last 90 days** include today. **Yesterday** is the one most recent full day. * **Payment flow**: **All payments** (the default), **Checkouts**, or **Subscription renewals**. * **Payment account**: **All payment accounts** (the default), or one payment account. Each account shows its name and its gateway. The list offers the accounts that can take payments in the mode you're viewing: active accounts, and inactive ones that had payments in the range. * **Live or test payments**: **Live payments** (the default) or **Test payments**. While you view test payments, a **Showing test data** badge appears at the end of the row. Switching between live and test sets **Payment account** back to **All payment accounts**, because the accounts differ between the two. * **Country**: if your company has more than one country, a country selector starts at **All countries**. Your default country is marked **(default)**. With a country selected, only payments recorded for that country are counted, and amounts are in that country's currency. When you choose **Custom range**, a calendar opens. Click a start day and an end day. A range can cover up to 92 days, and days after today can't be picked. The button next to **Date range** then shows the days you picked, and you can click it to pick again. Your filters are saved in the page's web address. You can bookmark a view, or send the link to someone else on your team. ### Payment health **Payment health** shows five figures for the range, with the dates and the period they're compared with, for example **compared with the previous 30 days**. The comparison period is the same number of days, just before your range. **Yesterday** is compared with the day before. | Figure | What it means | | - | - | | **Checkout success** | Of your checkouts that got an answer from the bank, the share where a payment was approved. Each checkout counts once. A shopper who is declined, tries again and is approved counts as one success. This is closest to what your shoppers experienced. | | **Approval rate** | Approved attempts out of every attempt the bank approved or declined, at checkout and on renewals. Every retry counts, so this rate is usually lower than **Checkout success**. | | **Card approval** | Of the different cards shoppers tried at checkout, the share that were approved. Renewals aren't included, because a renewal doesn't record which card it charged. A run of stolen cards moves this rate more than the other two. | | **Approved volume** | The value of approved payments, with how many there were. | | **Recovered** | The value of checkouts that were declined at first and then approved. | Under each rate, you see the counts behind it, for example **412 of 450 checkouts**, and how far it moved since the comparison period, in percentage points (**pts**). **Approved volume** shows its change as a percentage. A rate shows **n/a** when nothing in the range got an answer. That's different from 0%, which means every attempt was declined. ### Alerts Between **Payment health** and **Daily trend**, up to four alerts point out what needs your attention, most serious first. Each is labeled by how urgent it is: **Act now**, **Review**, **Note**, or **Good news**. When there's nothing to report, no alerts appear. | Alert | When it appears | What it suggests | | - | - | - | | Checkouts tried 3 or more different cards | At least one checkout tried 3 or more different cards. It's labeled **Act now** when 2 or more checkouts did, or one checkout tried 5 or more cards. Otherwise it's labeled **Review**. | Many cards on one checkout is how a stolen-card run looks. Review these shoppers before you ship their orders. **Show details** jumps to [Checkouts that tried many cards](#checkouts-that-tried-many-cards). | | Approval rate fell | Your approval rate dropped by 3 points or more compared with the earlier period, with at least 50 answered attempts in each period. | Check the decline reasons to see what changed. **Show details** jumps to [Why payments were declined](#why-payments-were-declined). | | Declines were processing errors | **Processing error** caused at least 5 declines and at least 5% of all declines. | Your shoppers' cards didn't cause these. Contact Fluid support if they continue. | | Only part of renewal attempts were approved | Fewer than 70% of at least 20 renewal attempts were approved. | Renewal retries and failed-payment emails are on the **Subscription Billing** page. **Open Subscription Billing** takes you there. | | Insufficient funds caused most declines | **Insufficient funds or limit** is the biggest decline cause, at 40% or more of declines. | These often clear on a later retry. Renewals retry on their own, and shoppers at checkout can use another card. | | Declined checkouts were not recovered | At least one checkout was declined, and no later attempt on it was approved. Shows how many and their value. | Some of these shoppers may have ordered again through a new checkout. | | Approval rate rose | Your approval rate rose by 3 points or more, with the same minimum volume as the drop alert. | More of your shoppers' payments went through on the first try. | ### Daily trend **Daily trend** has two charts for each day in the range: * A line chart of **Checkout success** (solid) and **Approval rate** (dashed). * A bar chart of **Approved attempts** and **Declined attempts**. Point at a day to see its numbers. A day with no answered attempts shows **No attempts** for its rates. If your range is a single day, you see **Pick a longer range to see the trend.** ### Why payments were declined Below the **Declines and breakdowns** label, **Why payments were declined** groups your declined attempts by cause, largest first. Each cause shows how many declines it caused and its share of all declines, what it means, and what you can do. It also shows how many happened at checkout and how many on renewals. A badge marks some causes. **Not caused by the shopper** means the shopper's card wasn't the problem. **Retries can help** means a later attempt with the same card may be approved. | Cause | What it means | What you can do | | - | - | - | | **Insufficient funds or limit** | The card had too little money or reached a spending limit. | Retrying later often works. Renewals retry on their own; shoppers at checkout can use another card. | | **Declined by the bank** | The card's bank refused the payment without a specific reason, for example "Do Not Honor". | Ask the shopper to call their bank or use another card. | | **Card not activated** | The bank has not activated this card yet. | The cardholder must activate the card with their bank. | | **Card closed, expired or lost** | The card can no longer be charged. | The shopper needs a new card. Ask subscribers to update their payment method. | | **Incorrect card details** | The card number, expiry date or security code was wrong. | A retry with the same details fails again. The shopper must enter the card again. | | **Recurring payments stopped** | The cardholder told their bank to stop recurring charges. | Don't retry. Contact the customer if they want to keep the subscription. | | **Processing error** | The gateway or the platform failed. The shopper's card did not cause it. | Contact Fluid support if these continue. | | **No reason given** | The gateway did not return a reason. | Check the transaction in the gateway's own dashboard. | | **Other bank responses** | A response that has no class yet. | Read the gateway's message for the cause. | To see the gateway's own wording, click **Gateway messages** under a cause. It lists up to three of the most frequent messages, with how many declines each one caused. If nothing was declined, the card shows **No declines in this range.** ### Where payments succeed and fail **Where payments succeed and fail** shows your approval rate split five ways. Click a tab to switch: * **Payment account**: each payment account, with its gateway. * **Card brand**: card payments only, such as Visa or Mastercard. * **Payment method**: **Card**, or the gateway for other payment methods. * **Checkout vs renewal**: **Checkout** and **Subscription renewal**. * **Country**: the country recorded on each payment. Payments with no country show as **Not recorded**. Each row shows **Attempts**, **Approval rate**, **Approved volume** and **Top decline cause**, the cause behind most of that row's declines. **Top decline cause** shows **None** when the row had no declines. A tab lists up to 8 rows. If there are more, the rest are added together in an **Other** row. A rate based on fewer than 20 answered attempts is greyed out, because a few declines can move it a lot. Point at it to see how many attempts it's based on. ### Checkouts that tried many cards **Checkouts that tried many cards** lists checkouts where the shopper tried 3 or more different cards. This card appears only when there's at least one. It shows up to 10, those with the most cards first. Each row shows the **Shopper email**, **Cards tried**, **Attempts**, **Declined**, the **Outcome** and the **Last attempt**. **Approved: review order** means one of the cards was eventually approved. Review that order before you ship it. **Not approved** means none of the cards went through. ### How these numbers are counted Click **How these numbers are counted**, at the bottom of the screen, to see how the screen counts: * An attempt is one charge request to the bank. Voids, refunds, capturing an earlier authorization, gateway status updates, and $0 or $1 card checks aren't attempts. That's why the approval rate here can differ from the **Transactions** page. * Approval is the bank's answer. An authorization counts as approved when the bank approves it, before you capture it. * Attempts still waiting for an answer count in the totals, but not in any rate. * Days follow your browser's time zone, which the note names. Amounts are in your company's currency, or the selected country's. ## Check how your payments are doing In **Date range**, choose a range, for example **Last 7 days**. To check one full day, choose **Yesterday**. To look at one part of your payments, choose a **Payment flow**, a **Payment account**, or a country. Check the alerts under **Payment health** first. Click **Show details** on an alert to jump to the panel behind it. In **Why payments were declined**, find the largest causes and follow the action shown for each. In **Where payments succeed and fail**, check whether one payment account, card brand or country has a lower approval rate than the rest. ## Check a test setup To confirm that test payments go through before you go live, choose **Test payments**. The screen then counts only test payments, and the **Showing test data** badge appears. Choose **Live payments** to switch back. ## Loading and refreshing While the screen loads, a placeholder shows where the panels will be. When you change a filter, the current numbers fade until the new ones arrive. The screen reloads its numbers every five minutes while it's open, so the newest payments in your range appear without a page refresh. The range's days are set when you open the screen. If you leave it open past midnight, reload the page to move the range forward. ## Frequently asked questions **Checkout success** counts each checkout once, even when the shopper tried several times. **Approval rate** counts every attempt, so each retry that was declined pulls it down. The more your shoppers retry, the bigger the gap between the two. This screen counts only charge requests to the bank. Voids, refunds, capturing an earlier authorization, gateway status updates, and $0 or $1 card checks aren't counted here, but the **Transactions** page counts them. No live payment got an answer in the range, the flow, the payment account or the country you chose. Try a longer range, or set the filters back to **All payments**, **All payment accounts** and **All countries**. If you're still setting up, choose **Test payments** to check your test transactions. If you open a saved link with a payment account that was since removed, you see **Payment performance couldn’t load for this payment account. It may have been removed. Try again to show all payment accounts.** Click **Try again** to show all payment accounts instead. **Performance** appears in the **Payments** group only if your role has **View only** or **Full access** for **Payment Reports**, in the **Commerce** card. If you lose that access while the screen is open, it shows **You no longer have access to payment performance.** Ask an admin who manages roles to update your role. See [Roles](/help/admin/settings/roles). **Processing error** declines come from the gateway or the platform, not from your shoppers' cards. If they keep happening, contact Fluid 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. ## Related pages * [Home](/help/admin/home) * [Gateways](/help/admin/settings/gateways) * [APM](/help/admin/settings/apm) * [Payment Routing](/help/admin/settings/payment-routing) * [Countries](/help/admin/settings/countries) * [Roles](/help/admin/settings/roles) * [Payment performance API reference](/api-reference/analytics_payments/payment-performance-over-a-date-range) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.