MCPTool reference
Other tools
Arguments, results, errors, and access, confirmation, and retry policy for each Other tool in FloPay MCP, from the reviewed API contract.
Other tools
Generated from the FloPay MCP contract version 1, revision 764b41d5c7205d6df7eeaeac832fafe882247f5526b1d4d6bc6f98e3eaca7784.
ClientInvoices_findOne
Get one Flo billing invoice for the authenticated client
| Policy | Value |
|---|---|
| Operation | GET /v1/client-invoices/{uuid} |
| Class | read-only |
| Risk | low |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | read |
| Roles | owner, admin, member |
| Scopes | mcp:read |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
uuid | path | string | Yes |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
adjustmentTotalUsd | number | Yes | Signed source-period billing adjustments applied to this invoice, in USD. |
charges | array of object | Yes | Durable monthly charges swept onto this invoice. |
charges[].amountUsd | number | Yes | Charge amount in USD. |
charges[].createdAt | string (date-time) | Yes | When the durable charge was created. |
charges[].currency | string | Yes | Allowed values: USD. |
charges[].id | string (uuid) | Yes | The durable client charge UUID. |
charges[].period | string | Yes | UTC calendar month to which the charge belongs. |
charges[].type | string | Yes | Allowed values: monthly_fee. |
clientId | string (uuid) | Yes | The client organisation billed by this invoice. |
createdAt | string (date-time) | Yes | When the invoice record was created. |
currency | string | Yes | Allowed values: USD. |
id | string (uuid) | Yes | The Flo-to-client invoice UUID. |
invoiceDate | string | Yes | Final UTC calendar date of the invoiced period. |
invoiceNumber | string | Yes | Global human-readable invoice number. |
issuedAt | string (date-time) | Yes | When the invoice was issued. |
issuerAddress | string | Yes | Issuer address snapshotted at issuance. |
issuerLegalName | string | Yes | Issuing legal entity snapshotted at issuance. |
minimumSpendAdjustmentUsd | number | Yes | Adjustment required to reach the minimum-spend floor, in USD. |
minimumSpendUsd | number | Yes | Minimum-spend floor captured when this invoice was issued, in USD. |
monthlyFeeTotalUsd | number | Yes | Monthly-fee charges linked to this invoice, in USD. |
outstandingTotalUsd | number | Yes | Amount still outstanding in USD. Settlement is full-only. |
period | string | Yes | First day of the invoiced UTC calendar month. |
settlement | object or null | No | Additive settlement state. Null for invoices issued before settlement tracking began. |
settlement.collectionMethod | string | Yes | Allowed values: automatic, manual. |
settlement.method | string or null | No | Allowed values: stripe_card, bank_transfer, other. |
settlement.settledAt | string (date-time) or null | No | Effective settlement date and time. |
settlement.status | string | Yes | Allowed values: awaiting_manual, pending, processing, retryable_failed, retry_exhausted, paid. |
status | string | Yes | Allowed values: issued, paid, void. |
taxTotalUsd | number or null | No | Reserved tax total; null while tax is out of scope. |
totalUsd | number | Yes | Net invoice total in USD. |
transactionFeeTotalUsd | number | Yes | Finalised transaction fees belonging to this period, in USD. |
Errors
| Status | Description |
|---|---|
400 | The supplied pagination query is invalid. |
401 | Client Basic or OAuth2 bearer authentication is required. |
404 | No invoice with the requested id exists for this client. |
ClientInvoices_list
List Flo billing invoices for the authenticated client
| Policy | Value |
|---|---|
| Operation | GET /v1/client-invoices |
| Class | read-only |
| Risk | low |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | read |
| Roles | owner, admin, member |
| Scopes | mcp:read |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
page | query | number | No | Page number for paginated list endpoints. Pagination is 1-based. Default: 1. Minimum: 1. |
limit | query | number | No | Maximum number of records to return per page for paginated list endpoints. Default: 20. Minimum: 1. Maximum: 100. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
data | array of object | Yes | |
data[].adjustmentTotalUsd | number | Yes | Signed source-period billing adjustments applied to this invoice, in USD. |
data[].charges | array of object | Yes | Durable monthly charges swept onto this invoice. |
data[].charges[].amountUsd | number | Yes | Charge amount in USD. |
data[].charges[].createdAt | string (date-time) | Yes | When the durable charge was created. |
data[].charges[].currency | string | Yes | Allowed values: USD. |
data[].charges[].id | string (uuid) | Yes | The durable client charge UUID. |
data[].charges[].period | string | Yes | UTC calendar month to which the charge belongs. |
data[].charges[].type | string | Yes | Allowed values: monthly_fee. |
data[].clientId | string (uuid) | Yes | The client organisation billed by this invoice. |
data[].createdAt | string (date-time) | Yes | When the invoice record was created. |
data[].currency | string | Yes | Allowed values: USD. |
data[].id | string (uuid) | Yes | The Flo-to-client invoice UUID. |
data[].invoiceDate | string | Yes | Final UTC calendar date of the invoiced period. |
data[].invoiceNumber | string | Yes | Global human-readable invoice number. |
data[].issuedAt | string (date-time) | Yes | When the invoice was issued. |
data[].issuerAddress | string | Yes | Issuer address snapshotted at issuance. |
data[].issuerLegalName | string | Yes | Issuing legal entity snapshotted at issuance. |
data[].minimumSpendAdjustmentUsd | number | Yes | Adjustment required to reach the minimum-spend floor, in USD. |
data[].minimumSpendUsd | number | Yes | Minimum-spend floor captured when this invoice was issued, in USD. |
data[].monthlyFeeTotalUsd | number | Yes | Monthly-fee charges linked to this invoice, in USD. |
data[].outstandingTotalUsd | number | Yes | Amount still outstanding in USD. Settlement is full-only. |
data[].period | string | Yes | First day of the invoiced UTC calendar month. |
data[].settlement | object or null | No | Additive settlement state. Null for invoices issued before settlement tracking began. |
data[].settlement.collectionMethod | string | Yes | Allowed values: automatic, manual. |
data[].settlement.method | string or null | No | Allowed values: stripe_card, bank_transfer, other. |
data[].settlement.settledAt | string (date-time) or null | No | Effective settlement date and time. |
data[].settlement.status | string | Yes | Allowed values: awaiting_manual, pending, processing, retryable_failed, retry_exhausted, paid. |
data[].status | string | Yes | Allowed values: issued, paid, void. |
data[].taxTotalUsd | number or null | No | Reserved tax total; null while tax is out of scope. |
data[].totalUsd | number | Yes | Net invoice total in USD. |
data[].transactionFeeTotalUsd | number | Yes | Finalised transaction fees belonging to this period, in USD. |
limit | number | Yes | |
page | number | Yes | |
pages | number | Yes | |
total | number | Yes |
Errors
| Status | Description |
|---|---|
400 | The supplied pagination query is invalid. |
401 | Client Basic or OAuth2 bearer authentication is required. |
Company_get
Get Company
Returns the authenticated merchant company.
| Policy | Value |
|---|---|
| Operation | GET /v1/company |
| Class | read-only |
| Risk | low |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | read |
| Roles | owner, admin, member |
| Scopes | mcp:read |
Arguments
This tool takes no arguments.
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
createdAt | string (date-time) | Yes | |
currency | string | Yes | |
id | string | Yes | |
slug | string | Yes | |
updatedAt | string (date-time) | Yes |
Errors
| Status | Description |
|---|---|
401 | Missing or invalid Basic API key or OAuth2 bearer token. |
Company_update
Update Company
Updates the authenticated merchant company. The reporting currency is the unit every merchant report and aggregate is expressed in; transactions keep their own source currency. Owners and admins only.
| Policy | Value |
|---|---|
| Operation | PATCH /v1/company |
| Class | mutating |
| Risk | medium |
| Confirmation | required |
| Retry | same-idempotency-key |
| Rate-limit tier | mutation |
| Roles | owner, admin |
| Scopes | mcp:write |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
currency | body | string | Yes | Allowed values: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SOS, SRD, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW. Minimum length: 3. Maximum length: 3. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
createdAt | string (date-time) | Yes | |
currency | string | Yes | |
id | string | Yes | |
slug | string | Yes | |
updatedAt | string (date-time) | Yes |
Errors
| Status | Description |
|---|---|
401 | Missing or invalid Basic API key or OAuth2 bearer token. |
DunningPolicy_get
Read the authenticated client's effective subscription dunning policy
| Policy | Value |
|---|---|
| Operation | GET /v1/settings/dunning-policy |
| Class | read-only |
| Risk | low |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | read |
| Roles | owner, admin |
| Scopes | mcp:read |
Arguments
This tool takes no arguments.
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
activeCampaignChanges | string | Yes | Allowed values: future_campaigns_only. Default: future_campaigns_only. |
cadence | object | Yes | |
cadence.day | object | Yes | |
cadence.day.maxScheduledRetries | number | Yes | Minimum: 1. Maximum: 8. |
cadence.day.retryWindowHours | number | Yes | Minimum: 1. Maximum: 1440. |
cadence.month | object | Yes | |
cadence.month.maxScheduledRetries | number | Yes | Minimum: 1. Maximum: 8. |
cadence.month.retryWindowHours | number | Yes | Minimum: 1. Maximum: 1440. |
cadence.week | object | Yes | |
cadence.week.maxScheduledRetries | number | Yes | Minimum: 1. Maximum: 8. |
cadence.week.retryWindowHours | number | Yes | Minimum: 1. Maximum: 1440. |
cadence.year | object | Yes | |
cadence.year.maxScheduledRetries | number | Yes | Minimum: 1. Maximum: 8. |
cadence.year.retryWindowHours | number | Yes | Minimum: 1. Maximum: 1440. |
effectiveAt | string (date-time) or null | Yes | |
eligibleDeclineReasons | array of string | Yes | Allowed values: INSUFFICIENT_FUNDS, DO_NOT_HONOUR, TOO_MANY_ATTEMPTS, PARTIAL_APPROVAL, PAYMENT_GATEWAY_ERROR, TECHNICAL_ERROR, RETRYABLE_DECLINE, UNSUPPORTED_CARD_PURCHASE, USER_ERROR, CVV_INVALID, AVS_FAIL, POSTCODE_INVALID, 3DS_FAIL, EXCEEDS_CARD_LIMIT, CLIENT_ERROR, UNKNOWN_DECLINE_REASON. |
permittedRetryTimesUtc | array of string or null | Yes | |
platformLimits | object | Yes | Default: {"clientCanChangeLifecycleEvents":false,"clientCanRetryNonRetryableOutcomes":false,"maxRetryWindowHours":1440,"maxRetryWindowHoursScope":"client_override","maxScheduledRetries":8,"platformDefaultRetryWindowScaling":"interval_count_before_next_billing_cycle","retriesMustBeBeforeNextBillingCycle":true}. |
platformLimits.clientCanChangeLifecycleEvents | boolean | Yes | Allowed values: false. Default: false. |
platformLimits.clientCanRetryNonRetryableOutcomes | boolean | Yes | Allowed values: false. Default: false. |
platformLimits.maxRetryWindowHours | object | Yes | Maximum retry window enforced for activated client overrides; the released platform default keeps interval-count scaling. Default: 1440. Maximum: 1440. |
platformLimits.maxRetryWindowHoursScope | string | Yes | Allowed values: client_override. Default: client_override. |
platformLimits.maxScheduledRetries | object | Yes | Default: 8. Maximum: 8. |
platformLimits.platformDefaultRetryWindowScaling | string | Yes | Allowed values: interval_count_before_next_billing_cycle. Default: interval_count_before_next_billing_cycle. |
platformLimits.retriesMustBeBeforeNextBillingCycle | boolean | Yes | Allowed values: true. Default: true. |
policyId | string (uuid) or null | Yes | |
revision | number or null | Yes | Minimum: 1. |
source | string | Yes | Allowed values: platform_default, client_override. |
Errors
| Status | Description |
|---|---|
401 | Client Basic or OAuth2 bearer authentication is required. |
403 | Members cannot manage dunning policy settings. |
ProductPrices_list
List Product Prices
Returns the authenticated merchant’s locally persisted product prices. Every row includes stable Flopay price and product identifiers, ISO-4217 currency, and catalog lifecycle status. Use relation=product to include the owning product identity. Invalid or unsupported list parameters return 400.
| Policy | Value |
|---|---|
| Operation | GET /v1/product-prices |
| Class | read-only |
| Risk | low |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | read |
| Roles | owner, admin, member |
| Scopes | mcp:read |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
page | query | integer | No | 1-based page number for paginated list endpoints. Default: 1. Minimum: 1. |
limit | query | integer | No | Maximum number of records to return per page. Default: 20. Minimum: 1. Maximum: 100. |
sort | query | string | No | Sort by one allowed field. Use exactly one of sort[asc] or sort[desc]. Allowed fields: amount, createdAt, currency, updatedAt, product.code, product.id, product.name, product.status. Default: createdAt DESC. Allowed values: amount, createdAt, currency, updatedAt, product.code, product.id, product.name, product.status. |
relation | query | string | No | Comma-separated relation aliases to include. Allowed aliases: product. Unknown aliases return 400. |
amount | query | number | No | Base price in major currency units. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
createdAt | query | string (date-time) | No | Price creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
currency | query | string | No | ISO-4217 price currency. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. |
id | query | string (uuid) | No | Stable Flopay product-price identifier. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. |
productId | query | string (uuid) | No | Stable Flopay identifier of the owning product. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. |
status | query | string | No | Catalog lifecycle state. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. Allowed values: active, inactive. |
updatedAt | query | string (date-time) | No | Price update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
variantId | query | string (uuid) | No | Stable Flopay identifier of the optional product variant. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. |
Result
Returns 200 with a JSON body. A tenant-scoped, paginated inventory of stable product-price records.
| Field | Type | Required | Description |
|---|---|---|---|
data | array of object | Yes | |
data[].amount | number | Yes | Base price in major units. |
data[].createdAt | string (date-time) | Yes | |
data[].currency | string | Yes | ISO-4217 currency code. |
data[].effectiveAmount | number | Yes | Sale price when the current time is in the sale window, otherwise the base amount. |
data[].id | string | Yes | |
data[].product | object | No | Owning product identity, present when relation=product is requested. |
data[].product.code | string | Yes | |
data[].product.id | string (uuid) | Yes | |
data[].product.name | string | Yes | |
data[].product.status | string | Yes | Allowed values: active, inactive. |
data[].productId | string (uuid) | Yes | Stable Flopay identifier of the owning product. |
data[].rebillAtSaleAmount | boolean | Yes | When false an active sale applies to the first subscription charge only (rebills revert to the full amount); when true the sale price is retained for the subscription lifetime. |
data[].saleAmount | number or null | Yes | Sale price; populated only when sale window is set. |
data[].saleEndsAt | string (date-time) or null | Yes | |
data[].saleStartsAt | string (date-time) or null | Yes | |
data[].status | string | Yes | Inactive prices remain readable but cannot be selected for new purchases. Allowed values: active, inactive. |
data[].updatedAt | string (date-time) | Yes | |
data[].variantId | string (uuid) or null | Yes | |
limit | number | Yes | |
page | number | Yes | |
pages | number | Yes | |
total | number | Yes |
Errors
| Status | Description |
|---|---|
400 | The sort, filter, relation, or pagination query parameters were invalid. |
401 | A valid client API key or OAuth2 bearer token is required. |
403 | The authenticated principal lacks merchant read access. |
SalesWatcherReviewHistory_findOne
Get one Sales Watcher review
| Policy | Value |
|---|---|
| Operation | GET /v1/sales-watcher/reviews/{id} |
| Class | read-only |
| Risk | low |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | read |
| Roles | owner, admin, member |
| Scopes | mcp:read |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | |
relation | query | string | No | This endpoint does not support relation aliases. Supplying relation returns 400. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
confidence | string or null | No | Allowed values: low, medium, high. |
expiresAt | string (date-time) | Yes | When this derived review expires under the 90-day retention policy. |
id | string (uuid) | Yes | The immutable Sales Watcher review id. |
outcome | string | Yes | Allowed values: clear, concern, inconclusive. |
resourceId | string | Yes | The safe opaque Flo resource id reviewed by the watcher. |
resourceType | string | Yes | Allowed values: transaction, checkout_attempt, subscription, processed_event, invoice, client_webhook_event. |
reviewedAt | string (date-time) | Yes | |
safeLinks | array of string | Yes | Read-only Flo dashboard links available to the client. |
severity | string or null | No | Allowed values: warning, critical, inconclusive. |
summary | string | Yes | Bounded, server-rendered summary without raw evidence or model content. |
Errors
| Status | Description |
|---|---|
400 | The supplied path or list query is invalid. |
401 | Client authentication is required. |
404 | No active review with the requested id exists for this client. |
SalesWatcherReviewHistory_list
List Sales Watcher review history
| Policy | Value |
|---|---|
| Operation | GET /v1/sales-watcher/reviews |
| Class | read-only |
| Risk | low |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | read |
| Roles | owner, admin, member |
| Scopes | mcp:read |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
page | query | integer | No | 1-based page number for paginated list endpoints. Default: 1. Minimum: 1. |
limit | query | integer | No | Maximum number of records to return per page. Default: 20. Minimum: 1. Maximum: 100. |
sort | query | string | No | Sort by one allowed field. Use exactly one of sort[asc] or sort[desc]. Allowed fields: createdAt, expiresAt, reviewedAt. Default: reviewedAt DESC. Allowed values: createdAt, expiresAt, reviewedAt. |
relation | query | string | No | This endpoint does not support relation aliases. Supplying relation returns 400. |
confidence | query | string | No | AI confidence recorded for the review, when an AI review ran. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. Allowed values: low, medium, high. |
expiresAt | query | string (date-time) | No | Review retention expiry timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
id | query | string (uuid) | No | Immutable Sales Watcher review UUID. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. |
outcome | query | string | No | Derived Sales Watcher review outcome. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. Allowed values: clear, concern, inconclusive. |
resourceId | query | string | No | Safe opaque Flo resource id. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. |
resourceType | query | string | No | Type of Flo resource reviewed. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. Allowed values: transaction, checkout_attempt, subscription, processed_event, invoice, client_webhook_event. |
reviewedAt | query | string (date-time) | No | Timestamp at which the resource was reviewed. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
severity | query | string | No | Highest derived concern severity, when present. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. Allowed values: warning, critical, inconclusive. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
data | array of object | Yes | |
data[].confidence | string or null | No | Allowed values: low, medium, high. |
data[].expiresAt | string (date-time) | Yes | When this derived review expires under the 90-day retention policy. |
data[].id | string (uuid) | Yes | The immutable Sales Watcher review id. |
data[].outcome | string | Yes | Allowed values: clear, concern, inconclusive. |
data[].resourceId | string | Yes | The safe opaque Flo resource id reviewed by the watcher. |
data[].resourceType | string | Yes | Allowed values: transaction, checkout_attempt, subscription, processed_event, invoice, client_webhook_event. |
data[].reviewedAt | string (date-time) | Yes | |
data[].safeLinks | array of string | Yes | Read-only Flo dashboard links available to the client. |
data[].severity | string or null | No | Allowed values: warning, critical, inconclusive. |
data[].summary | string | Yes | Bounded, server-rendered summary without raw evidence or model content. |
limit | number | Yes | |
page | number | Yes | |
pages | number | Yes | |
total | number | Yes |
Errors
| Status | Description |
|---|---|
400 | The supplied path or list query is invalid. |
401 | Client authentication is required. |
Webhooks tools
Arguments, results, errors, and access, confirmation, and retry policy for each Webhooks tool in FloPay MCP, from the reviewed API contract.
Confirmed actions
How FloPay MCP runs mutating tools, from a preview that changes nothing to explicit confirmation, safe retries, and what to do when an outcome is unclear.