> ## 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 over a date range > Returns the Payments > Performance page in one payload: three rates, the trend, decline reasons, breakdowns and checkouts that tried many cards, for the range and for the range of equal length just before it. The three rates answer different questions. `checkout_success_rate` is the share of checkouts with an approved attempt, counting a checkout once however often it retried. `approval_rate` is approved over answered attempts, which retries pull down. `card_approval_rate` is distinct checkout cards approved over distinct checkout cards tried, which a stolen-card run moves most. Approval is the issuer's answer: an authorization counts when approved, before capture. Decline reasons use `Commerce::Payments::DeclineClassifier`, the classes renewal dunning acts on. Money is in the company's currency, or the selected country's. ## OpenAPI ````yaml /api-reference/analytics-v2026-04.yaml get /api/v202604/analytics/payments/overview openapi: 3.1.0 info: title: Fluid Analytics Dashboard v2026-04 API version: v2026-04 description: | Endpoints backing the fluid-admin Analytics section (Home / Traffic / Brand Buzz). One endpoint per card on each tab; the frontend polls independently so each card can have its own refresh cadence. contact: email: support@fluid.app license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.fluid.app security: - bearer_auth: [] tags: - name: analytics_dashboard_home_overview description: | Home > Overview tab cards. Card 1 (header tiles) is served here; cards 2-11 land in subsequent PRs. - name: analytics_dashboard_home_live description: | Home > Live tab cards. Card 1 (header tiles) is served here; cards 2-6 land in subsequent PRs. - name: analytics_dashboard_home_field description: | Home > Field tab cards. Card 1 (field momentum header) is served here; cards 2-5 land in subsequent PRs. - name: analytics_subscription_billing description: | Subscription Billing surface — a month of renewals worked day by day, plus that month's failure reporting. Same `reports.view` gate and country scoping as the Home dashboard cards. The day drawer's per-subscription table is not served here; it is a paginated list on `GET /api/subscriptions`, which already accepts `next_bill_date` and `last_failed_at` range filters. - name: analytics_payments x-fluid-section: Payments description: | Payments > Performance page: approval rates, decline reasons and breakdowns over a date range. Same `reports.view` gate and country scoping as the Home dashboard cards. An attempt is one charge a shopper's money rode on, counted once: voids, refunds, the capture half of an authorize and capture, webhook echoes and card checks are not attempts. paths: /api/v202604/analytics/payments/overview: get: tags: - analytics_payments summary: Payment performance over a date range description: | Returns the Payments > Performance page in one payload: three rates, the trend, decline reasons, breakdowns and checkouts that tried many cards, for the range and for the range of equal length just before it. The three rates answer different questions. `checkout_success_rate` is the share of checkouts with an approved attempt, counting a checkout once however often it retried. `approval_rate` is approved over answered attempts, which retries pull down. `card_approval_rate` is distinct checkout cards approved over distinct checkout cards tried, which a stolen-card run moves most. Approval is the issuer's answer: an authorization counts when approved, before capture. Decline reasons use `Commerce::Payments::DeclineClassifier`, the classes renewal dunning acts on. Money is in the company's currency, or the selected country's. operationId: getAnalyticsPaymentsOverview parameters: - $ref: '#/components/parameters/PaymentRangeFromQueryParam' - $ref: '#/components/parameters/PaymentRangeToQueryParam' - $ref: '#/components/parameters/TimeZoneQueryParam' - $ref: '#/components/parameters/CountryQueryParam' - $ref: '#/components/parameters/PaymentModeQueryParam' - $ref: '#/components/parameters/PaymentFlowQueryParam' - $ref: '#/components/parameters/PaymentAccountQueryParam' responses: '200': description: Payment performance payload content: application/json: schema: $ref: '#/components/schemas/PaymentPerformanceResponse' example: from: '2026-10-06' to: '2026-10-07' previous_from: '2026-10-04' previous_to: '2026-10-05' time_zone: America/Denver currency: USD mode: live summary: attempt_count: 120 approved_count: 104 declined_count: 16 pending_count: 0 approved_amount: '12480.0' checkout_attempt_count: 98 checkout_approved_count: 90 renewal_attempt_count: 22 renewal_approved_count: 14 checkout_count: 92 successful_checkout_count: 90 recovered_checkout_count: 5 recovered_amount: '640.0' unrecovered_checkout_count: 2 unrecovered_amount: '210.0' multi_card_checkout_count: 1 card_count: 101 approved_card_count: 96 unidentified_card_decline_count: 1 approval_rate: '86.7' checkout_success_rate: '97.8' checkout_approval_rate: '91.8' renewal_approval_rate: '63.6' card_approval_rate: '95.0' previous_summary: attempt_count: 0 approved_count: 0 declined_count: 0 pending_count: 0 approved_amount: '0.0' checkout_attempt_count: 0 checkout_approved_count: 0 renewal_attempt_count: 0 renewal_approved_count: 0 checkout_count: 0 successful_checkout_count: 0 recovered_checkout_count: 0 recovered_amount: '0.0' unrecovered_checkout_count: 0 unrecovered_amount: '0.0' multi_card_checkout_count: 0 card_count: 0 approved_card_count: 0 unidentified_card_decline_count: 0 approval_rate: null checkout_success_rate: null checkout_approval_rate: null renewal_approval_rate: null card_approval_rate: null days: - date: '2026-10-06' attempt_count: 64 approved_count: 55 declined_count: 9 approved_amount: '6620.0' checkout_count: 49 successful_checkout_count: 48 approval_rate: '85.9' checkout_success_rate: '98.0' - date: '2026-10-07' attempt_count: 56 approved_count: 49 declined_count: 7 approved_amount: '5860.0' checkout_count: 43 successful_checkout_count: 42 approval_rate: '87.5' checkout_success_rate: '97.7' decline_reasons: - category: balance declined_count: 9 checkout_count: 4 renewal_count: 5 share: '56.3' retriable: true customer_caused: true messages: - text: Insufficient funds count: 8 - text: Exceeds withdrawal limit count: 1 - category: integration declined_count: 2 checkout_count: 2 renewal_count: 0 share: '12.5' retriable: true customer_caused: false messages: [] breakdowns: flow: - key: checkout label: Checkout detail: null attempt_count: 98 approved_count: 90 declined_count: 8 approved_amount: '11020.0' approval_rate: '91.8' top_decline_category: soft_issuer card_brand: - key: visa label: Visa detail: null attempt_count: 80 approved_count: 70 declined_count: 10 approved_amount: '8400.0' approval_rate: '87.5' top_decline_category: balance payment_account: - key: '524' label: Stripe US detail: Stripe attempt_count: 120 approved_count: 104 declined_count: 16 approved_amount: '12480.0' approval_rate: '86.7' top_decline_category: balance payment_method: - key: CreditCard label: Card detail: null attempt_count: 120 approved_count: 104 declined_count: 16 approved_amount: '12480.0' approval_rate: '86.7' top_decline_category: balance country: - key: US label: United States detail: null attempt_count: 120 approved_count: 104 declined_count: 16 approved_amount: '12480.0' approval_rate: '86.7' top_decline_category: balance multi_card_checkouts: - email: shopper@example.com card_count: 3 attempt_count: 4 declined_count: 3 approved: true last_attempt_at: '2026-10-07T02:18:23Z' payment_accounts: - id: 524 label: Stripe US detail: Stripe '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/Unprocessable' components: parameters: PaymentRangeFromQueryParam: name: from in: query required: false description: | First day of the range, inclusive, as `YYYY-MM-DD` in the `tz` zone. Defaults to 29 days before `to`, so the default range is thirty days. A value that is not this exact shape returns `400`. schema: type: string format: date example: '2026-09-08' PaymentRangeToQueryParam: name: to in: query required: false description: | Last day of the range, inclusive, as `YYYY-MM-DD` in the `tz` zone. Defaults to today, or to 29 days after `from` when only `from` is sent. A range longer than 92 days, or one that ends before it starts, returns `400`. schema: type: string format: date example: '2026-10-07' TimeZoneQueryParam: name: tz in: query required: false description: | IANA timezone name (e.g. `America/Denver`) or Rails-style alias (`Eastern Time (US & Canada)`) used to anchor "today" boundaries and hour-of-day bucketing. The frontend sends `Intl.DateTimeFormat().resolvedOptions().timeZone`. Unknown or malformed values silently fall back to UTC — callers omit the param when the endpoint doesn't need wall-clock alignment (see CURRENT-3077). schema: type: string example: America/Denver CountryQueryParam: name: country in: query required: false description: | ISO alpha-2 code of one of the requesting company's configured countries (see `GET /countries`). When present, every service on this endpoint filters its data to that country and reports money in the country's own currency. Omit (or send `"all"`) for the aggregate-across-countries view, which is the default and matches pre-Phase-004 behavior. Unknown ISO codes or ones the company is not configured for return `400`. schema: type: string example: US PaymentModeQueryParam: name: mode in: query required: false description: | Which payments to report on. `live` (the default) is real money through a live account at a real gateway. `test` is every test or sandbox account and the Bogus gateway, so a merchant who is still integrating can watch their own test traffic. schema: type: string enum: - live - test example: live PaymentFlowQueryParam: name: flow in: query required: false description: | Narrow every figure to one flow. `checkout` is an attempt with a cart; `renewal` is a subscription renewal with no cart. `all`, the default, keeps both. schema: type: string enum: - all - checkout - renewal example: all PaymentAccountQueryParam: name: payment_account_id in: query required: false description: | Narrow every figure to one of the company's payment accounts, by the `id` listed in `payment_accounts`. An id that is not one of the company's accounts returns `400`. schema: type: string pattern: ^[0-9]+$ example: '524' schemas: PaymentPerformanceResponse: type: object properties: from: type: string format: date to: type: string format: date previous_from: type: string format: date description: First day of the range of equal length just before. previous_to: type: string format: date time_zone: type: string description: IANA name of the zone the dates are cut in. currency: $ref: '#/components/schemas/Currency' mode: type: string enum: - live - test summary: $ref: '#/components/schemas/PaymentPerformanceSummary' previous_summary: $ref: '#/components/schemas/PaymentPerformanceSummary' days: type: array description: One entry per date of the range, zero-filled. items: $ref: '#/components/schemas/PaymentPerformanceDay' decline_reasons: type: array description: Most declines first. items: $ref: '#/components/schemas/PaymentDeclineReason' breakdowns: $ref: '#/components/schemas/PaymentBreakdowns' multi_card_checkouts: type: array maxItems: 10 description: | Checkouts that tried three or more different cards, most cards first. Many cards on one cart is how a stolen-card run looks from the merchant's side. items: $ref: '#/components/schemas/PaymentMultiCardCheckout' payment_accounts: type: array description: The company's kept accounts in this mode, for the filter. items: $ref: '#/components/schemas/PaymentAccountOption' meta: $ref: '#/components/schemas/Meta' required: - from - to - previous_from - previous_to - time_zone - currency - mode - summary - previous_summary - days - decline_reasons - breakdowns - multi_card_checkouts - payment_accounts Currency: type: string description: ISO 4217 three-letter code (uppercase). example: USD minLength: 3 maxLength: 3 PaymentPerformanceSummary: type: object description: | Counts for one range. Pending attempts are counted in `attempt_count` but are in no rate's denominator. properties: attempt_count: type: integer minimum: 0 description: Every attempt, pending included. approved_count: type: integer minimum: 0 declined_count: type: integer minimum: 0 pending_count: type: integer minimum: 0 description: Attempts with no answer yet. approved_amount: $ref: '#/components/schemas/Money' checkout_attempt_count: type: integer minimum: 0 description: Approved plus declined checkout attempts. checkout_approved_count: type: integer minimum: 0 renewal_attempt_count: type: integer minimum: 0 description: Approved plus declined renewal attempts. renewal_approved_count: type: integer minimum: 0 checkout_count: type: integer minimum: 0 description: | Checkouts (carts) with at least one answered attempt, each counted once however many times it retried. successful_checkout_count: type: integer minimum: 0 description: | Checkouts with an approved attempt. An authorization counts when the issuer approves it, before any capture. recovered_checkout_count: type: integer minimum: 0 description: Successful checkouts that were declined at least once first. recovered_amount: $ref: '#/components/schemas/Money' unrecovered_checkout_count: type: integer minimum: 0 description: | Declined checkouts with no approval. The shopper may still have bought through a different cart. unrecovered_amount: $ref: '#/components/schemas/Money' multi_card_checkout_count: type: integer minimum: 0 description: Checkouts that tried three or more different cards. card_count: type: integer minimum: 0 description: | Distinct checkout cards with an answered attempt. Renewals are not counted: no record names the card a renewal charged. approved_card_count: type: integer minimum: 0 unidentified_card_decline_count: type: integer minimum: 0 description: | Checkout card declines whose card was never stored, usually a failed card add, so the card cannot be counted. approval_rate: $ref: '#/components/schemas/NullablePercentage' checkout_success_rate: $ref: '#/components/schemas/NullablePercentage' checkout_approval_rate: $ref: '#/components/schemas/NullablePercentage' renewal_approval_rate: $ref: '#/components/schemas/NullablePercentage' card_approval_rate: $ref: '#/components/schemas/NullablePercentage' required: - attempt_count - approved_count - declined_count - pending_count - approved_amount - checkout_attempt_count - checkout_approved_count - renewal_attempt_count - renewal_approved_count - checkout_count - successful_checkout_count - recovered_checkout_count - recovered_amount - unrecovered_checkout_count - unrecovered_amount - multi_card_checkout_count - card_count - approved_card_count - unidentified_card_decline_count - approval_rate - checkout_success_rate - checkout_approval_rate - renewal_approval_rate - card_approval_rate PaymentPerformanceDay: type: object properties: date: type: string format: date attempt_count: type: integer minimum: 0 approved_count: type: integer minimum: 0 declined_count: type: integer minimum: 0 approved_amount: $ref: '#/components/schemas/Money' checkout_count: type: integer minimum: 0 description: Checkouts whose first attempt in the range fell on this date. successful_checkout_count: type: integer minimum: 0 approval_rate: $ref: '#/components/schemas/NullablePercentage' checkout_success_rate: $ref: '#/components/schemas/NullablePercentage' required: - date - attempt_count - approved_count - declined_count - approved_amount - checkout_count - successful_checkout_count - approval_rate - checkout_success_rate PaymentDeclineReason: type: object properties: category: $ref: '#/components/schemas/PaymentDeclineCategory' declined_count: type: integer minimum: 1 checkout_count: type: integer minimum: 0 renewal_count: type: integer minimum: 0 share: $ref: '#/components/schemas/Percentage' retriable: type: boolean description: Whether renewal dunning keeps retrying a decline of this class. customer_caused: type: boolean description: >- False for `integration` and `unknown`, which are not the shopper's card. messages: type: array maxItems: 3 description: | The most frequent gateway texts, most frequent first. Empty for `integration`, whose texts describe platform internals rather than the shopper's card, and for `unknown`. items: $ref: '#/components/schemas/PaymentDeclineMessage' required: - category - declined_count - checkout_count - renewal_count - share - retriable - customer_caused - messages PaymentBreakdowns: type: object description: | Each dimension's rows, most attempts first. After eight rows the rest fold into one `other` row. Card brand counts card payments only. properties: flow: type: array items: $ref: '#/components/schemas/PaymentBreakdownRow' card_brand: type: array items: $ref: '#/components/schemas/PaymentBreakdownRow' payment_account: type: array items: $ref: '#/components/schemas/PaymentBreakdownRow' payment_method: type: array items: $ref: '#/components/schemas/PaymentBreakdownRow' country: type: array items: $ref: '#/components/schemas/PaymentBreakdownRow' required: - flow - card_brand - payment_account - payment_method - country PaymentMultiCardCheckout: type: object description: | No cart token is returned: it is the bearer credential the public cart routes accept. properties: email: type: - string - 'null' card_count: type: integer minimum: 3 attempt_count: type: integer minimum: 1 declined_count: type: integer minimum: 0 approved: type: boolean description: Whether any of the checkout's attempts was approved. last_attempt_at: type: string format: date-time required: - email - card_count - attempt_count - declined_count - approved - last_attempt_at PaymentAccountOption: type: object properties: id: type: integer label: type: string detail: type: - string - 'null' description: The account's gateway or provider. required: - id - label - detail Meta: type: object properties: request_id: type: - string - 'null' request_uuid: type: - string - 'null' description: >- Identifier of the request that produced this response, for support correlation. timestamp: type: string format: date-time required: - timestamp ErrorResponse: type: object properties: error: type: object properties: message: type: string details: type: object additionalProperties: true required: - message meta: $ref: '#/components/schemas/Meta' required: - error LegacyUnauthorizedResponse: type: object properties: message: type: string required: - message LegacyForbiddenResponse: type: object properties: message: type: string error: type: string minProperties: 1 Money: type: string description: | Decimal amount, expressed as a string to preserve arbitrary precision across the wire. Parsed to Number on the client and formatted with `Intl.NumberFormat`. Once the in-flight money-cents-migration lands, this will switch to a `{ amount_cents: integer, currency: string }` object. example: '180.25' NullablePercentage: type: - string - 'null' description: | A percentage as a decimal string rounded to one decimal place, or `null` when the divisor was zero. Null and `"0.0"` differ: null means nothing was attempted, `"0.0"` means every attempt failed. example: '86.4' PaymentDeclineCategory: type: string description: | The `Commerce::Payments::DeclineClassifier` class of a decline, the same classes renewal dunning acts on. `balance`: funds or a spending limit. `soft_issuer`: a transient issuer refusal such as Do Not Honor. `card_activation`: the card was never activated. `card_gone`: closed, expired or reported lost. `never_retry`: wrong card number or security code. `stop_requested`: the cardholder revoked recurring payments. `integration`: a platform or gateway failure, not the shopper's card. `unknown`: no reason was recorded. `unrecognized`: a reason with no pattern yet. enum: - balance - soft_issuer - card_activation - card_gone - integration - never_retry - stop_requested - unknown - unrecognized example: balance Percentage: type: string description: | A percentage share, expressed as a decimal string rounded to one decimal place. `"100.0"` when a single bucket accounts for the full total; `"0.0"` when the divisor was zero. example: '42.5' PaymentDeclineMessage: type: object properties: text: type: string description: The gateway's own wording, trimmed to 160 characters. count: type: integer minimum: 1 required: - text - count PaymentBreakdownRow: type: object properties: key: type: - string - 'null' description: | The dimension value: a flow, canonical card brand, payment account id, integration class or ISO country code. `other` for the folded tail; null when the value was not recorded. label: type: string detail: type: - string - 'null' description: Secondary label, such as a payment account's gateway. attempt_count: type: integer minimum: 0 approved_count: type: integer minimum: 0 declined_count: type: integer minimum: 0 approved_amount: $ref: '#/components/schemas/Money' approval_rate: $ref: '#/components/schemas/NullablePercentage' top_decline_category: oneOf: - $ref: '#/components/schemas/PaymentDeclineCategory' - type: 'null' description: The most frequent decline class, or null with no declines. required: - key - label - detail - attempt_count - approved_count - declined_count - approved_amount - approval_rate - top_decline_category responses: InvalidRequest: description: | A query parameter the endpoint cannot act on — a `country` the requesting company is not configured for, a `month` that is not `YYYY-MM`, or a `date` that is not `YYYY-MM-DD`. All are caller errors rather than scoping failures, and all render the structured error envelope. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Missing or invalid bearer token content: application/json: schema: $ref: '#/components/schemas/LegacyUnauthorizedResponse' Forbidden: description: | Token present but the caller is not a company admin (or is one without `reports.view`). Both branches render via legacy `authorize_*` helpers whose response predates the structured error envelope, so the body is the flat legacy shape. content: application/json: schema: $ref: '#/components/schemas/LegacyForbiddenResponse' Unprocessable: description: An Analytics service returned a business-rule failure. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearer_auth: type: http scheme: bearer description: | Bearer token authentication. Requires a company-admin token whose role holds `reports.view`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.