Skip to main content
Glama
flowsery

flowsery

Official

Track Payment

track_payment
Destructive

Record analytics payments and refunds to attribute revenue without charging customers or moving money; skip it when a connected payment provider already tracks revenue to avoid double counting.

Instructions

Record an analytics payment; this never charges a customer, moves money, or issues a refund. Revenue appears in get_overview, get_timeseries, every breakdown's revenue column, and the visitor profile. Skip it when the site's provider (Stripe, LemonSqueezy, Polar, and other connected providers) is tracked automatically, or the revenue is counted twice; use track_goal for conversions without revenue. transactionId must be unique: a repeated id is rejected, not deduplicated. A new payment also records a payment goal completion (free_trial when amount is 0); isRenewal skips that. isRefund with an existing transactionId overwrites that payment's recorded refund amount and any supplied customer attribution instead of adding a row. Attribution looks up a known visitor by visitorUid, customerId, or email; with no match the revenue is kept but its source shows as Unknown. Send email and name only when the user supplied them and wants the payment attributed. Undo with delete_payments. Requires websiteId or domain with a workspace token.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "amount": "<amount>",
      "currency": "<currency>",
      "transactionId": "<transactionId>"
    },
    "name": "track_payment"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoCustomer name shown on the payment
emailNoCustomer email, used only to attribute the payment to a known visitor
amountYesPayment amount in major currency units (e.g. 29.99). With isRefund, the amount refunded. 0 records a free_trial goal instead of a payment goal.
domainNoWebsite domain from list_websites (e.g. "example.com"). Alternative to websiteId with a workspace token.
currencyYesCurrency code (e.g. "USD", "EUR")
isRefundNoTrue to record a refund that already happened. With an existing transactionId, marks that payment refunded by amount instead of creating a new record.
timezoneNoThe visitor's IANA timezone (e.g. "Europe/Berlin"). Helps place the visitor in a country when the call comes from a server or proxy.
isRenewalNoTrue for recurring or renewal charges. Renewals count in revenue but do not record the automatic payment goal.
timestampNoISO 8601 time the payment happened (e.g. "2026-01-15T10:30:00Z"), for backfilling. Defaults to now.
websiteIdNoWebsite ID from list_websites. Required with a workspace token unless domain is given; ignored with a website key.
customerIdNoCustomer ID from the payment provider. Also used to find the visitor when visitorUid is absent.
customerIpNoThe buyer's IP address at checkout, for a server-side call that cannot match the payment to a visitor. Flowsery keeps only the country it resolves from it.
sessionUidNoSession ID of the visitor's current session (the _fs_sid value), so the payment is tied to that session
visitorUidNoAnonymous visitor ID Flowsery assigned on the user's own website (the _fs_vid value). Without it, or a customerId or email matching a known visitor, the payment is attributed to Unknown.
workspaceIdNoWorkspace to act in: an id from list_workspaces. Omit to use the default workspace. Use the same workspaceId for every call about the same workspace, since ids from one workspace do not exist in another
transactionIdYesUnique transaction ID from the payment provider. Must not repeat across payments; reuse it only with isRefund to mark that payment refunded.
customerUserAgentNoThe buyer's User-Agent at checkout, for the same case. Flowsery keeps the browser, OS and device it resolves from it.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed20 schema fields changedv1.5.0
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • addedInput schema / properties / customerIp
      Added value: +{
      +  "description": "The buyer's IP address at checkout, for a server-side call that cannot match the payment to a visitor. Flowsery keeps only the country it resolves from it.",
      +  "type": "string"
      +}
    • addedInput schema / properties / customerUserAgent
      Added value: +{
      +  "description": "The buyer's User-Agent at checkout, for the same case. Flowsery keeps the browser, OS and device it resolves from it.",
      +  "maxLength": 1024,
      +  "type": "string"
      +}
    • changedInput schema / properties / email / description
      Previous value: -"Customer email"New value: +"Customer email, used only to attribute the payment to a known visitor"
    • changedInput schema / properties / isRefund / description
      Previous value: -"True to record a refund. With an existing transactionId, marks that payment refunded by amount instead of creating a new record."New value: +"True to record a refund that already happened. With an existing transactionId, marks that payment refunded by amount instead of creating a new record."
    • changedInput schema / properties / isRenewal / description
      Previous value: -"True for recurring/renewal charges. Renewals are counted in revenue but do not record the automatic payment goal."New value: +"True for recurring or renewal charges. Renewals count in revenue but do not record the automatic payment goal."
    • changedInput schema / properties / name / description
      Previous value: -"Customer name"New value: +"Customer name shown on the payment"
    • changedInput schema / properties / sessionUid / description
      Previous value: -"Session ID for the current visitor session"New value: +"Session ID of the visitor's current session (the _fs_sid value), so the payment is tied to that session"
    • addedInput schema / properties / timestamp
      Added value: +{
      +  "description": "ISO 8601 time the payment happened (e.g. \"2026-01-15T10:30:00Z\"), for backfilling. Defaults to now.",
      +  "type": "string"
      +}
    • addedInput schema / properties / timezone
      Added value: +{
      +  "description": "The visitor's IANA timezone (e.g. \"Europe/Berlin\"). Helps place the visitor in a country when the call comes from a server or proxy.",
      +  "type": "string"
      +}
    • changedInput schema / properties / transactionId / description
      Previous value: -"Unique transaction ID from your payment provider. Must not repeat across payments; reuse it only with isRefund to mark that payment refunded."New value: +"Unique transaction ID from the payment provider. Must not repeat across payments; reuse it only with isRefund to mark that payment refunded."
    • changedInput schema / properties / visitorUid / description
      Previous value: -"Visitor UID from the _fs_vid cookie. Strongly recommended: without it (or customerId/email matching a known visitor) the payment is attributed to Unknown"New value: +"Anonymous visitor ID Flowsery assigned on the user's own website (the _fs_vid value). Without it, or a customerId or email matching a known visitor, the payment is attributed to Unknown."
    • addedInput schema / properties / workspaceId
      Added value: +{
      +  "description": "Workspace to act in: an id from list_workspaces. Omit to use the default workspace. Use the same workspaceId for every call about the same workspace, since ids from one workspace do not exist in another",
      +  "type": "string"
      +}
    • removedOutput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • addedOutput schema / properties / result / additionalProperties
      Added value: +true
    • removedOutput schema / properties / result / description
      Removed value: -"Object with status and data: a confirmation message once the payment is stored."
    • addedOutput schema / properties / result / properties
      Added value: +{
      +  "data": {
      +    "description": "One confirmation message once the payment is stored",
      +    "items": {
      +      "additionalProperties": true,
      +      "properties": {
      +        "message": {
      +          "type": "string"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "type": "array"
      +  },
      +  "status": {
      +    "description": "\"success\" on every successful call",
      +    "type": "string"
      +  }
      +}
    • addedOutput schema / properties / result / required
      Added value: +[
      +  "status",
      +  "data"
      +]
    • addedOutput schema / properties / result / type
      Added value: +"object"
    • addedOutput schema / required
      Added value: +[
      +  "result"
      +]
  2. Changed9 schema fields changedv0.1.1
    • changedInput schema / properties / amount / description
      Previous value: -"Payment amount (e.g. 29.99)"New value: +"Payment amount in major currency units (e.g. 29.99). With isRefund, the amount refunded. 0 records a free_trial goal instead of a payment goal."
    • changedInput schema / properties / customerId / description
      Previous value: -"Customer ID from payment provider"New value: +"Customer ID from the payment provider. Also used to find the visitor when visitorUid is absent."
    • changedInput schema / properties / domain / description
      Previous value: -"Website domain to query. Required when using a workspace token unless websiteId is provided."New value: +"Website domain from list_websites (e.g. \"example.com\"). Alternative to websiteId with a workspace token."
    • changedInput schema / properties / isRefund / description
      Previous value: -"True for refunded payments"New value: +"True to record a refund. With an existing transactionId, marks that payment refunded by amount instead of creating a new record."
    • changedInput schema / properties / isRenewal / description
      Previous value: -"True for recurring/renewal payments"New value: +"True for recurring/renewal charges. Renewals are counted in revenue but do not record the automatic payment goal."
    • changedInput schema / properties / transactionId / description
      Previous value: -"Unique transaction ID from your payment provider"New value: +"Unique transaction ID from your payment provider. Must not repeat across payments; reuse it only with isRefund to mark that payment refunded."
    • changedInput schema / properties / visitorUid / description
      Previous value: -"Visitor UID from _fs_vid cookie — strongly recommended for accurate revenue attribution"New value: +"Visitor UID from the _fs_vid cookie. Strongly recommended: without it (or customerId/email matching a known visitor) the payment is attributed to Unknown"
    • changedInput schema / properties / websiteId / description
      Previous value: -"Website ID to query. Required when using a workspace token unless domain is provided."New value: +"Website ID from list_websites. Required with a workspace token unless domain is given; ignored with a website key."
    • changedOutput schema / properties / result / description
      Previous value: -"Confirmation of the recorded payment."New value: +"Object with status and data: a confirmation message once the payment is stored."
  3. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantial behavior the annotations cannot convey: rejected duplicate transactionIds, the automatic payment-goal side effect (free_trial at amount 0), isRefund overwriting an existing payment's refund amount and attribution instead of inserting, and the Unknown-attribution fallback. Remaining minor gap: it does not say what the tool returns on success, though an output schema exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The safety clarification and the skip/alternative rule are front-loaded, which is the right ordering. It is one dense paragraph rather than segmented, and a few clauses (provider enumeration, attribution caveats) pack multiple behaviors per sentence, but no sentence is filler given the 17-parameter surface.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, 17-parameter write tool, the description covers the safety framing, deduplication contract, goal side effects, refund overwrite semantics, attribution rules, undo path, and auth requirement (websiteId or domain with a workspace token). Return values are covered by the output schema and per-field detail by the fully documented schema, so nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description goes beyond the schema on the highest-risk fields: transactionId uniqueness/reuse rules, isRefund's overwrite-versus-insert semantics, the visitorUid/customerId/email lookup order, and the instruction to send email and name only when supplied and attributed. It leaves the lower-risk params (timestamp, timezone, customerIp, sessionUid) to the schema, which documents them adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Record an analytics payment" names a specific verb and resource, then immediately disambiguates with "this never charges a customer, moves money, or issues a refund," which separates an analytics bookkeeping record from any real payment action. It also names track_goal as the non-revenue sibling, so an agent can route without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the negative condition ("Skip it when the site's provider ... is tracked automatically, or the revenue is counted twice"), names the alternative for the adjacent case ("use track_goal for conversions without revenue"), and gives the undo path ("Undo with delete_payments"). Preconditions, exclusions, and alternatives are all explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.